
                       Tcl 8.4a2 Commands



_________________________________________________________________

NAME
     after - Execute a command after a time delay

SYNOPSIS
	after ms
	after ms ?script script script ...?
	after cancel id
	after cancel script script script ...
	after idle ?script script script ...?
	after info ?id?

_________________________________________________________________

DESCRIPTION 
     This command is used to delay execution of the program or to execute a
     command in background sometime in the future. It  has  several  forms,
     depending on the first argument to the command:
          after ms
               Ms must be an integer giving a  time  in  milliseconds.  The
               command sleeps for ms milliseconds and then  returns.  While
               the command is sleeping the application does not respond  to
               events. 
          after ms ?script script script ...?
               In  this  form  the  command  returns  immediately,  but  it
               arranges for a Tcl command to be  executed  ms  milliseconds
               later as an event handler.  The  command  will  be  executed
               exactly once, at the given  time.  The  delayed  command  is
               formed by concatenating all the script arguments in the same
               fashion as the concat command. The command will be  executed
               at global level (outside the context of any Tcl  procedure).
               If an error occurs while executing the delayed command  then
               the bgerror mechanism is used to report the error. The after
               command returns an identifier that can be used to cancel the
               delayed command using after cancel.
          after cancel id
               Cancels the execution of a delayed    command    that    was
               previously scheduled. Id indicates which command  should  be
               canceled; it must have been the return value from a previous
               after command. If the command given by id has  already  been
               executed then the after cancel command has no effect.
          after cancel script script ...
               This  command  also  cancels  the  execution  of  a  delayed
               command. The script arguments are concatenated together with
               space separators (just as in the concat command).  If  there
               is  a  pending  command  that  matches  the  string,  it  is
               cancelled and will never be executed; if no such command  is
               currently pending then  the  after  cancel  command  has  no
               effect. 
          after idle script ?script script ...?
               Concatenates the script arguments  together    with    space
               separators (just as in the concat command), and arranges for
               the resulting script  to  be  evaluated  later  as  an  idle
               callback. The script will be run exactly once, the next time
               the event loop  is  entered  and  there  are  no  events  to
               process. The command returns an identifier that can be  used
               to cancel the delayed command  using  after  cancel.  If  an
               error occurs while executing the  script  then  the  bgerror
               mechanism is used to report the error.
          after info ?id?
               This command returns information  about    existing    event
               handlers. If no id argument is supplied, the command returns
               a list of the identifiers for all  existing  event  handlers
               created by the after command for this interpreter. If id  is
               supplied, it specifies an existing  handler;  id  must  have
               been the return value from some previous call to  after  and
               it must not have triggered yet or been  cancelled.  In  this
               case the command returns a list with two elements. The first
               element of the list is the script associated  with  id,  and
               the second element is either idle or timer to indicate  what
               kind of event handler it is.
     The after ms and after idle forms  of  the  command  assume  that  the
     application is event driven: the delayed commands will not be executed
     unless the application enters the event loop. In applications that are
     not normally event-driven, such  as  tclsh,  the  event  loop  can  be
     entered with the vwait and update commands.


SEE ALSO
     bgerror, concat, update, vwait

KEYWORDS 
     cancel, delay, idle callback, sleep, time






_________________________________________________________________

NAME
     append - Append to variable

SYNOPSIS
	append varName ?value value value ...?

_________________________________________________________________

DESCRIPTION 
     Append all of the value arguments to the  current  value  of  variable
     varName. If varName doesn't exist, it is given a value  equal  to  the
     concatenation of all the value arguments.  This  command  provides  an
     efficient way to build up long variables incrementally.  For  example,
     ``append a $b'' is much more efficient than ``set a $a$b''  if  $a  is
     long. 


SEE ALSO
     concat, lappend

KEYWORDS 
     append, variable






_________________________________________________________________

NAME
     array - Manipulate array variables

SYNOPSIS
	array option arrayName ?arg arg ...?

_________________________________________________________________

DESCRIPTION 
     This command performs one of several operations on the variable  given
     by arrayName.  Unless  otherwise  specified  for  individual  commands
     below, arrayName must be the name of an existing array  variable.  The
     option argument determines what action is carried out by the  command.
     The legal options (which may be abbreviated) are:
          array anymore arrayName searchId
               Returns 1  if  there  are  any  more  elements  left  to  be
               processed in an array search, 0 if all elements have already
               been returned. SearchId indicates which search on  arrayName
               to check, and  must  have  been  the  return  value  from  a
               previous invocation of array  startsearch.  This  option  is
               particularly useful if an array has an element with an empty
               name, since the return value from  array  nextelement  won't
               indicate whether the search has been completed.
          array donesearch arrayName searchId
               This command terminates an array search and destroys all the
               state associated with that search. SearchId indicates  which
               search on arrayName to  destroy,  and  must  have  been  the
               return value from a    previous    invocation    of    array
               startsearch. Returns an empty string.
          array exists arrayName
               Returns 1 if arrayName is an array variable, 0 if  there  is
               no variable by that name or if it is a scalar variable.
          array get arrayName ?pattern?
               Returns a list  containing  pairs  of  elements.  The  first
               element in each pair is the name of an element in  arrayName
               and the second element of each pair  is  the  value  of  the
               array element. The order  of  the  pairs  is  undefined.  If
               pattern is not specified, then all of the  elements  of  the
               array are included in the result. If pattern  is  specified,
               then only those elements whose names  match  pattern  (using
               the  matching  rules  of  string  match)  are  included.  If
               arrayName isn't the name of an array  variable,  or  if  the
               array contains no elements, then an empty list is returned.
          array names arrayName ?mode? ?pattern?
               Returns a list containing the names of all of  the  elements
               in the array that match pattern. Mode may be one of  -exact,
               -glob, or  -regexp.  If  specified,  mode  designates  which
               matching rules to use to match pattern against the names  of
               the elements in the array. If not specified,  mode  defaults
               to  -glob.  See  the  documentation  for  string  match  for
               information on glob style matching,  and  the  documentation
               for regexp for information on regexp matching. If pattern is
               omitted then the command returns all of the element names in
               the array. If there are no (matching) elements in the array,
               or if arrayName isn't the name of an array variable, then an
               empty string is returned.
          array nextelement arrayName searchId
               Returns the name of the next element  in  arrayName,  or  an
               empty string if all elements of arrayName have already  been
               returned in this search. The  searchId  argument  identifies
               the search, and must have been the return value of an  array
               startsearch command. Warning: if elements are  added  to  or
               deleted from the array, then all searches are  automatically
               terminated just as if array  donesearch  had  been  invoked;
               this will cause array nextelement  operations  to  fail  for
               those searches.
          array set arrayName list
               Sets the values of one or more elements in  arrayName.  list
               must have a form like that returned by array get, consisting
               of an even number of elements. Each odd-numbered element  in
               list is treated as an element name within arrayName, and the
               following element in list is used as a new  value  for  that
               array element. If the variable arrayName  does  not  already
               exist and list is empty, arrayName is created with an  empty
               array value.
          array size arrayName
               Returns a decimal string giving the number  of  elements  in
               the array. If arrayName isn't the name of an array then 0 is
               returned. 
          array startsearch arrayName
               This command initializes  an    element-by-element    search
               through the array given by arrayName, such that  invocations
               of the array nextelement command will return  the  names  of
               the individual elements in the array. When  the  search  has
               been completed,  the  array  donesearch  command  should  be
               invoked. The return value is a search identifier  that  must
               be used in array nextelement and array donesearch  commands;
               it allows multiple searches to  be  underway  simultaneously
               for the same array.
          array statistics arrayName
               Returns statistics about the distribution of data within the
               hashtable that represents the  array.    This    information
               includes the number of entries in the table, the  number  of
               buckets, and the utilization of the buckets.
          array unset arrayName ?pattern?
               Unsets all of the elements in the array that  match  pattern
               (using the matching rules of  string  match).  If  arrayName
               isn't the name of an array variable or there are no matching
               elements in the array, no error will be raised.  If  pattern
               is omitted and arrayName is  an  array  variable,  then  the
               command unsets the entire array. The command always  returns
               an empty string.

SEE ALSO
     list, string, variable, trace

KEYWORDS 
     array, element names, search






_________________________________________________________________

NAME
     bgerror - Command invoked to process background errors

SYNOPSIS
	bgerror message

_________________________________________________________________

DESCRIPTION 
     The bgerror command doesn't exist as built-in part  of  Tcl.  Instead,
     individual applications or users can define a bgerror command (e.g. as
     a Tcl procedure) if they wish to handle background errors.
     A background error is one that occurs in  an  event  handler  or  some
     other command that didn't originate with the application. For example,
     if an error occurs while executing a command specified with the  after
     command, then it is a background error. For  a  non-background  error,
     the error can  simply  be  returned  up  through  nested  Tcl  command
     evaluations until it reaches the top-level code  in  the  application;
     then the application can report the error in whatever way  it  wishes.
     When a background error occurs, the unwinding ends in the Tcl  library
     and there is no obvious way for Tcl to report the error.
     When Tcl detects a background error, it saves  information  about  the
     error and invokes the bgerror command later as an idle event  handler.
     Before invoking bgerror, Tcl  restores  the  errorInfo  and  errorCode
     variables to their values at the time  the  error  occurred,  then  it
     invokes bgerror with the error  message  as  its  only  argument.  Tcl
     assumes that the application has implemented the bgerror command,  and
     that the command will report the error in a way that makes  sense  for
     the application. Tcl will ignore any result returned  by  the  bgerror
     command as long as no error is generated.
     If another Tcl error occurs within the bgerror command  (for  example,
     because no bgerror command has been  defined)  then  Tcl  reports  the
     error itself by writing a message to stderr.
     If several background errors accumulate before bgerror is  invoked  to
     process them, bgerror will be invoked once  for  each  error,  in  the
     order  they  occurred.  However,  if  bgerror  returns  with  a  break
     exception, then any  remaining  errors  are  skipped  without  calling
     bgerror. 
     Tcl has no default implementation    for    bgerror.    However,    in
     applications using Tk there is a default bgerror procedure which posts
     a dialog box containing the error message and offers the user a chance
     to see a stack trace showing where the error occurred. In addition  to
     allowing the user to view the stack  trace,  the  dialog  provides  an
     additional application configurable button  which  may  be  used,  for
     example, to save the stack trace to a file. By default,  this  is  the
     behavior associated with that button. This behavior can  be  redefined
     by setting the option database values  *ErrorDialog.function.text,  to
     specify the caption for  the        function        button,        and
     *ErrorDialog.function.command, to specify the command to be  run.  The
     text of the stack  trace  is  appended  to  the  command  when  it  is
     evaluated. If either of these options is set to the empty string, then
     the additional button will not be displayed in the dialog.


SEE ALSO
     after, tclvars

KEYWORDS 
     background error, reporting






_________________________________________________________________

NAME
     binary - Insert and extract fields from binary strings

SYNOPSIS
	binary format formatString ?arg arg ...?
	binary scan string formatString ?varName varName ...?

_________________________________________________________________

DESCRIPTION 
     This command provides facilities for  manipulating  binary  data.  The
     first form, binary format, creates a binary  string  from  normal  Tcl
     values. For example,  given  the  values  16  and  22,  on  a  32  bit
     architecture, it might produce an 8-byte binary string  consisting  of
     two 4-byte integers, one for each of the numbers. The second  form  of
     the command, binary scan, does the opposite: it extracts data  from  a
     binary string and returns it as ordinary Tcl string values.


BINARY FORMAT
     The binary format command generates a binary string  whose  layout  is
     specified by  the  formatString  and  whose  contents  come  from  the
     additional arguments. The resulting binary value is returned.
     The formatString  consists  of  a  sequence  of  zero  or  more  field
     specifiers separated by zero or more spaces. Each field specifier is a
     single type character followed by  an  optional  numeric  count.  Most
     field specifiers consume one  argument  to  obtain  the  value  to  be
     formatted. The type  character  specifies  how  the  value  is  to  be
     formatted. The  count  typically  indicates  how  many  items  of  the
     specified type are taken from the value. If present, the  count  is  a
     non-negative decimal integer or *, which normally indicates  that  all
     of the items in the value are to be used. If the number  of  arguments
     does not match the number of fields in the format string that  consume
     arguments, then an error is generated.
     Each type-count pair moves an  imaginary  cursor  through  the  binary
     data, storing bytes at the current position and advancing  the  cursor
     to just after the  last  byte  stored.  The  cursor  is  initially  at
     position 0 at the beginning of the data. The type may be  any  one  of
     the following characters:
          a 
               Stores a character string of  length  count  in  the  output
               string. If arg has fewer than count bytes,  then  additional
               zero bytes are used to pad out the field. If arg  is  longer
               than the specified length,  the  extra  characters  will  be
               ignored. If count is *, then all of the bytes in arg will be
               formatted. If count is omitted, then one character  will  be
               formatted. For example,  binary  format  a7a*a  alpha  bravo
               charlie    will    return    a    string    equivalent    to
               alpha\000\000bravoc. 
          A 
               This form is the same as a except that spaces are  used  for
               padding instead of nulls. For example, binary  format  A6A*A
               alpha bravo charlie will return alpha bravoc.
          b 
               Stores a string of count binary digits in low-to-high  order
               within each byte in the output string. Arg  must  contain  a
               sequence of 1 and 0  characters.  The  resulting  bytes  are
               emitted in first to last order with the bits being formatted
               in low-to-high order within each byte. If arg has fewer than
               count digits, then zeros will  be  used  for  the  remaining
               bits. If arg has more than the specified number  of  digits,
               the extra digits will be ignored. If count is *, then all of
               the digits in arg will be formatted. If  count  is  omitted,
               then one digit will be formatted.  If  the  number  of  bits
               formatted does not end at a  byte  boundary,  the  remaining
               bits of the last byte will be  zeros.  For  example,  binary
               format b5b* 11100 111000011010 will    return    a    string
               equivalent to \x07\x87\x05.
          B 
               This form is the same as b except that the bits  are  stored
               in high-to-low order within each byte. For  example,  binary
               format B5B* 11100 111000011010 will    return    a    string
               equivalent to \xe0\xe1\xa0.
          h 
               Stores a string of count hexadecimal digits  in  low-to-high
               within each byte in the output string. Arg  must  contain  a
               sequence of       characters        in        the        set
               ``0123456789abcdefABCDEF''. The resulting bytes are  emitted
               in first to last order with the hex digits  being  formatted
               in low-to-high order within each byte. If arg has fewer than
               count digits, then zeros will  be  used  for  the  remaining
               digits. If arg has more than the specified number of digits,
               the extra digits will be ignored. If count is *, then all of
               the digits in arg will be formatted. If  count  is  omitted,
               then one digit will be formatted. If the  number  of  digits
               formatted does not end at a  byte  boundary,  the  remaining
               bits of the last byte will be  zeros.  For  example,  binary
               format h3h* AB  def  will  return  a  string  equivalent  to
               \xba\x00\xed\x0f. 
          H 
               This form is the same as h except that the digits are stored
               in high-to-low order within each byte. For  example,  binary
               format H3H* ab  DEF  will  return  a  string  equivalent  to
               \xab\x00\xde\xf0. 
          c 
               Stores one or  more  8-bit  integer  values  in  the  output
               string. If no count is specified, then arg must  consist  of
               an integer value; otherwise  arg  must  consist  of  a  list
               containing at least count integer elements. The low-order  8
               bits of each integer are stored as a one-byte value  at  the
               cursor position. If count is *, then all of the integers  in
               the list are formatted. If the number  of  elements  in  the
               list is fewer than count, then an error is generated. If the
               number of elements in the list is greater than  count,  then
               the extra elements are ignored. For example,  binary  format
               c3cc* {3 -3 128 1} 260 {2 5} will return a string equivalent
               to \x03\xfd\x80\x04\x02\x05, whereas binary format c  {2  5}
               will generate an error.
          s 
               This form is the same as c except that it stores one or more
               16-bit integers in little-endian byte order  in  the  output
               string. The low-order 16-bits of each integer are stored  as
               a two-byte value at  the  cursor  position  with  the  least
               significant byte stored first. For example, binary format s3
               {3 -3 258 1} will  return    a    string    equivalent    to
               \x03\x00\xfd\xff\x02\x01. 
          S 
               This form is the same as s except that it stores one or more
               16-bit integers in  big-endian  byte  order  in  the  output
               string. For example, binary format S3  {3  -3  258  1}  will
               return a string equivalent to \x00\x03\xff\xfd\x01\x02.
          i 
               This form is the same as c except that it stores one or more
               32-bit integers in little-endian byte order  in  the  output
               string. The low-order 32-bits of each integer are stored  as
               a four-byte value at the  cursor  position  with  the  least
               significant byte stored first. For example, binary format i3
               {3 -3 65536 1} will return   a    string    equivalent    to
               \x03\x00\x00\x00\xfd\xff\xff\xff\x00\x00\x01\x00 
          I 
               This form is the same as i except that it stores one or more
               one or more 32-bit integers in big-endian byte order in  the
               output string. For example, binary format I3 {3 -3 65536  1}
               will return      a        string        equivalent        to
               \x00\x00\x00\x03\xff\xff\xff\xfd\x00\x01\x00\x00 
          f 
               This form is the same as c except that it stores one or more
               one or  more  single-precision  floating  in  the  machine's
               native representation in    the    output    string.    This
               representation is not portable across architectures,  so  it
               should not be used to  communicate  floating  point  numbers
               across the network. The size of a floating point number  may
               vary across architectures, so the number of bytes  that  are
               generated may vary. If the  value  overflows  the  machine's
               native representation, then the value of FLT_MAX as  defined
               by the  system  will  be  used  instead.  Because  Tcl  uses
               double-precision floating-point  numbers  internally,  there
               may be some loss of precision  in    the    conversion    to
               single-precision. For example, on a Windows  system  running
               on an Intel Pentium processor, binary format  f2  {1.6  3.4}
               will return      a        string        equivalent        to
               \xcd\xcc\xcc\x3f\x9a\x99\x59\x40. 
          d 
               This form is the same as f except that it stores one or more
               one or  more  double-precision  floating  in  the  machine's
               native representation in the output string. For example,  on
               a Windows system running  on  an  Intel  Pentium  processor,
               binary format d1 {1.6} will return a  string  equivalent  to
               \x9a\x99\x99\x99\x99\x99\xf9\x3f. 
          x 
               Stores count null bytes in the output string.  If  count  is
               not  specified,  stores  one  null  byte.  If  count  is  *,
               generates an error. This type does not consume an  argument.
               For example, binary format a3xa3x2a3 abc def ghi will return
               a string equivalent to abc\000def\000\000ghi.
          X 
               Moves the cursor back count bytes in the output  string.  If
               count is * or is larger than the  current  cursor  position,
               then the cursor is positioned at location 0 so that the next
               byte stored will be the first byte in the result string.  If
               count is omitted then the cursor is  moved  back  one  byte.
               This type does not consume an argument. For example,  binary
               format a3X*a3X2a3 abc def ghi will return dghi.
          @ 
               Moves the cursor to the  absolute  location  in  the  output
               string specified by count. Position 0 refers  to  the  first
               byte in the output string. If count  refers  to  a  position
               beyond the last byte stored so far, then null bytes will  be
               placed in the unitialized locations and the cursor  will  be
               placed at the specified location. If count is  *,  then  the
               cursor is moved to the current end of the output string.  If
               count is omitted, then an error will be generated. This type
               does not consume an argument.  For  example,  binary  format
               a5@2a1@*a3@10a1 abcde f ghi j will return abfdeghi\000\000j.
                
BINARY SCAN
     The binary scan command parses fields from a binary string,  returning
     the number of conversions performed. String  gives  the  input  to  be
     parsed and formatString indicates how to parse it. Each varName  gives
     the name of a variable; when a field is scanned from string the result
     is assigned to the corresponding variable.
     As with binary format, the formatString  consists  of  a  sequence  of
     zero or more field specifiers separated by zero or more  spaces.  Each
     field specifier is a single type character  followed  by  an  optional
     numeric count. Most field specifiers consume one  argument  to  obtain
     the variable into which the scanned values should be placed. The  type
     character specifies how the binary data  is  to  be  interpreted.  The
     count typically indicates how many items of  the  specified  type  are
     taken from the data. If present, the count is a  non-negative  decimal
     integer or *, which normally indicates that all of the remaining items
     in the data are to be used. If there are not enough bytes  left  after
     the current cursor position to satisfy the  current  field  specifier,
     then the corresponding variable is  left  untouched  and  binary  scan
     returns immediately with the number of variables  that  were  set.  If
     there are not enough arguments for all of the  fields  in  the  format
     string that consume arguments, then an error is generated.
     It is important to note that the c, s, and S (and i  and  I  on  64bit
     systems) will be scanned into long data size values.  In  doing  this,
     values that have their high  bit  set  (0x80  for  chars,  0x8000  for
     shorts,  0x80000000  for  ints),  will  be  sign  extended.  Thus  the
     following will occur: set signShort [binary format s1  0x8000]  binary
     scan $signShort s1 val; # val == 0xFFFF8000 If you want to produce  an
     unsigned value, then you can mask the  return  value  to  the  desired
     size. For example, to produce an unsigned short value: set  val  [expr
     {$val & 0xFFFF}]; # val == 0x8000
     Each type-count pair moves an  imaginary  cursor  through  the  binary
     data, reading bytes from the current position. The cursor is initially
     at position 0 at the beginning of the data. The type may be any one of
     the following characters:
          a 
               The data is a character string of length count. If count  is
               *, then all of the remaining bytes in string will be scanned
               into the variable. If count is omitted, then  one  character
               will be scanned.  For  example,  binary  scan  abcde\000fghi
               a6a10 var1 var2 will return 1 with the string equivalent  to
               abcde\000 stored in var1 and var2 left unmodified.
          A 
               This form is the same as a, except trailing blanks and nulls
               are stripped from the scanned value before it is  stored  in
               the variable. For example, binary scan "abc efghi  \000"  A*
               var1 will return 1 with abc efghi stored in var1.
          b 
               The data is turned into a string of count binary  digits  in
               low-to-high order represented as a  sequence  of  ``1''  and
               ``0'' characters. The data bytes are  scanned  in  first  to
               last order with the bits being taken  in  low-to-high  order
               within each byte. Any  extra  bits  in  the  last  byte  are
               ignored. If count is *, then all of the  remaining  bits  in
               string will be scanned. If count is omitted,  then  one  bit
               will be scanned. For example, binary scan \x07\x87\x05  b5b*
               var1 var2 will return  2  with  11100  stored  in  var1  and
               1110000110100000 stored in var2.
          B 
               This form is the same as b, except the  bits  are  taken  in
               high-to-low order within each byte. For example, binary scan
               \x70\x87\x05 B5B* var1 var2 will return 2 with 01110  stored
               in var1 and 1000011100000101 stored in var2.
          h 
               The data is turned into a string of count hexadecimal digits
               in low-to-high order represented as a sequence of characters
               in the set ``0123456789abcdef''. The data bytes are  scanned
               in first to last order with the hex digits  being  taken  in
               low-to-high order within each byte. Any extra  bits  in  the
               last byte are ignored. If  count  is  *,  then  all  of  the
               remaining hex digits in string will be scanned. If count  is
               omitted, then one hex digit will be  scanned.  For  example,
               binary scan \x07\x86\x05 h3h* var1 var2 will return  2  with
               706 stored in var1 and 50 stored in var2.
          H 
               This form is the same as h, except the digits are  taken  in
               high-to-low order within each byte. For example, binary scan
               \x07\x86\x05 H3H* var1 var2 will return 2 with 078 stored in
               var1 and 05 stored in var2.
          c 
               The data is turned into  count  8-bit  signed  integers  and
               stored in the corresponding variable as a list. If count  is
               *, then all  of  the  remaining  bytes  in  string  will  be
               scanned. If count is omitted, then one 8-bit integer will be
               scanned. For example, binary  scan  \x07\x86\x05  c2c*  var1
               var2 will return 2 with 7 -122 stored in var1 and  5  stored
               in var2. Note that the integers  returned  are  signed,  but
               they can be converted to unsigned 8-bit quantities using  an
               expression like: expr ( $num + 0x100 ) % 0x100
          s 
               The data is interpreted  as  count  16-bit  signed  integers
               represented in little-endian byte order.  The  integers  are
               stored in the corresponding variable as a list. If count  is
               *, then all  of  the  remaining  bytes  in  string  will  be
               scanned. If count is omitted, then one 16-bit  integer  will
               be scanned.    For        example,        binary        scan
               \x05\x00\x07\x00\xf0\xff s2s* var1 var2 will return 2 with 5
               7 stored in var1 and -16  stored  in  var2.  Note  that  the
               integers returned are signed, but they can be  converted  to
               unsigned 16-bit quantities using an expression like: expr  (
               $num + 0x10000 ) % 0x10000
          S 
               This form  is  the  same  as  s  except  that  the  data  is
               interpreted as count 16-bit signed integers  represented  in
               big-endian byte  order.    For    example,    binary    scan
               \x00\x05\x00\x07\xff\xf0 S2S* var1 var2 will return 2 with 5
               7 stored in var1 and -16 stored in var2.
          i 
               The data is interpreted  as  count  32-bit  signed  integers
               represented in little-endian byte order.  The  integers  are
               stored in the corresponding variable as a list. If count  is
               *, then all  of  the  remaining  bytes  in  string  will  be
               scanned. If count is omitted, then one 32-bit  integer  will
               be scanned.    For        example,        binary        scan
               \x05\x00\x00\x00\x07\x00\x00\x00\xf0\xff\xff\xff  i2i*  var1
               var2 will return 2 with 5 7 stored in var1 and -16 stored in
               var2. Note that the integers returned are signed and  cannot
               be represented by Tcl as unsigned values.
          I 
               This form  is  the  same  as  I  except  that  the  data  is
               interpreted as count 32-bit signed integers  represented  in
               big-endian byte order.     For        example,        binary
               \x00\x00\x00\x05\x00\x00\x00\x07\xff\xff\xff\xf0  I2I*  var1
               var2 will return 2 with 5 7 stored in var1 and -16 stored in
               var2. 
          f 
               The data is interpreted as count  single-precision  floating
               point numbers in the machine's  native  representation.  The
               floating point  numbers  are  stored  in  the  corresponding
               variable as a list. If count is *, then all of the remaining
               bytes in string will be scanned. If count is  omitted,  then
               one single-precision floating point number will be  scanned.
               The  size  of  a  floating  point  number  may  vary  across
               architectures, so the number of bytes that are  scanned  may
               vary. If the data does not represent a valid floating  point
               number,  the  resulting  value  is  undefined  and  compiler
               dependent. For example, on a Windows system  running  on  an
               Intel Pentium processor, binary scan \x3f\xcc\xcc\xcd f var1
               will return 1 with 1.6000000238418579 stored in var1.
          d 
               This form  is  the  same  as  f  except  that  the  data  is
               interpreted as count double-precision floating point numbers
               in the machine's native representation. For  example,  on  a
               Windows system running on an Intel Pentium processor, binary
               scan \x9a\x99\x99\x99\x99\x99\xf9\x3f d var1 will  return  1
               with 1.6000000000000001 stored in var1.
          x 
               Moves the cursor forward count bytes in string. If count  is
               * or is larger than the number of bytes  after  the  current
               cursor cursor position, then the cursor is positioned  after
               the last byte in string.  If  count  is  omitted,  then  the
               cursor is moved forward one byte. Note that this  type  does
               not consume an argument.   For    example,    binary    scan
               \x01\x02\x03\x04 x2H* var1 will return 1 with 0304 stored in
               var1. 
          X 
               Moves the cursor back count bytes in string. If count  is  *
               or is larger than the  current  cursor  position,  then  the
               cursor is positioned at location 0 so  that  the  next  byte
               scanned will be the  first  byte  in  string.  If  count  is
               omitted then the cursor is moved back one  byte.  Note  that
               this type does not consume an argument. For example,  binary
               scan \x01\x02\x03\x04 c2XH* var1 var2 will return 2 with 1 2
               stored in var1 and 020304 stored in var2.
          @ 
               Moves the cursor to the absolute location in the data string
               specified by count. Note that position 0 refers to the first
               byte in string. If count refers to a position beyond the end
               of string, then the cursor  is  positioned  after  the  last
               byte. If count is omitted, then an error will be  generated.
               For example, binary scan \x01\x02\x03\x04 c2@1H*  var1  var2
               will return 2 with 1 2 stored in var1 and 020304  stored  in
               var2. 
PLATFORM ISSUES
     Sometimes it is desirable to format or  scan  integer  values  in  the
     native byte order for the machine. Refer to the byteOrder  element  of
     the tcl_platform array to decide which  type  character  to  use  when
     formatting or scanning integers.


SEE ALSO
     format, scan, tclvars

KEYWORDS 
     binary, format, scan





_________________________________________________________________

NAME
     break - Abort looping command

SYNOPSIS
	break

_________________________________________________________________

DESCRIPTION 
     This command is typically invoked inside the body of a looping command
     such as for or foreach or while. It returns a  TCL_BREAK  code,  which
     causes a break exception to occur. The exception  causes  the  current
     script to be aborted out to the  innermost  containing  loop  command,
     which then aborts its execution and returns normally. Break exceptions
     are also handled in a few other situations, such as the catch command,
     Tk event bindings, and the outermost scripts of procedure bodies.


SEE ALSO
     catch, continue, for, foreach, while

KEYWORDS 
     abort, break, loop






_________________________________________________________________

NAME
     catch - Evaluate script and trap exceptional returns

SYNOPSIS
	catch script ?varName?

_________________________________________________________________

DESCRIPTION 
     The catch command may be used to prevent errors from aborting  command
     interpretation. Catch calls the Tcl interpreter recursively to execute
     script, and always returns without raising an error, regardless of any
     errors that might occur while executing script.
     If script raises an error, catch will return a non-zero integer  value
     corresponding to one of the exceptional return codes  (see  tcl.h  for
     the definitions of code values). If the  varName  argument  is  given,
     then  the  variable  it  names  is  set  to  the  error  message  from
     interpreting script.
     If script does not raise an error, catch will return  0  (TCL_OK)  and
     set the variable to the value returned from script.
     Note that catch catches all exceptions, including those  generated  by
     break and continue as well as errors. The only  errors  that  are  not
     caught are syntax errors found when the script is  compiled.  This  is
     because the catch command only catches errors during runtime. When the
     catch statement is compiled, the script is compiled as  well  and  any
     syntax errors will generate a Tcl error.


EXAMPLES 
     The catch command may be used in an if to branch based on the  success
     of a script.

if { [catch {open $someFile w} fid] } {
    puts stderr "Could not open $someFile for writing\n$fid"
    exit 1
}
The catch command will not catch compiled syntax errors.  The
first time proc foo is called, the body will be compiled and a
Tcl error will be generated. 

proc foo {} {
    catch {expr {1 +- }}
}

SEE ALSO
     error, break, continue

KEYWORDS 
     catch, error






_________________________________________________________________

NAME
     cd - Change working directory

SYNOPSIS
	cd ?dirName?

_________________________________________________________________

DESCRIPTION 
     Change the current working  directory  to  dirName,  or  to  the  home
     directory (as specified in the HOME environment variable)  if  dirName
     is not given. Returns an empty string.


SEE ALSO
     filename, glob, pwd

KEYWORDS 
     working directory






_________________________________________________________________

NAME
     clock - Obtain and manipulate time

SYNOPSIS
	clock option ?arg arg ...?

_________________________________________________________________

DESCRIPTION 
     This command performs one of several operations  that  may  obtain  or
     manipulate strings or values that represent some notion of  time.  The
     option argument determines what action is carried out by the  command.
     The legal options (which may be abbreviated) are:
          clock clicks ?-milliseconds?
               Return a high-resolution time value  as  a  system-dependent
               integer value. The unit of the value is system-dependent but
               should be the highest  resolution  clock  available  on  the
               system such as a CPU  cycle  counter.  If  -milliseconds  is
               specified, then the value is guaranteed to be of millisecond
               granularity. This value should only be used for the relative
               measurement of elapsed time.
          clock format clockValue ?-format string? ?-gmt boolean?
               Converts an integer time value, typically returned by  clock
               seconds, clock scan, or the atime, mtime, or  ctime  options
               of the file command, to human-readable form. If the  -format
               argument is present the  next  argument  is  a  string  that
               describes how the date and time are to be  formatted.  Field
               descriptors consist of a % followed by  a  field  descriptor
               character. All other characters are copied into the  result.
               Valid field descriptors are:
                    %% 
                         Insert a %.
                    %a 
                         Abbreviated weekday name (Mon, Tue, etc.).
                    %A 
                         Full weekday name (Monday, Tuesday, etc.).
                    %b 
                         Abbreviated month name (Jan, Feb, etc.).
                    %B 
                         Full month name.
                    %c 
                         Locale specific date and time.
                    %d 
                         Day of month (01 - 31).
                    %H 
                         Hour in 24-hour format (00 - 23).
                    %I 
                         Hour in 12-hour format (00 - 12).
                    %j 
                         Day of year (001 - 366).
                    %m 
                         Month number (01 - 12).
                    %M 
                         Minute (00 - 59).
                    %p 
                         AM/PM indicator.
                    %S 
                         Seconds (00 - 59).
                    %U 
                         Week of year (00 - 52), Sunday is the first day of
                         the week.
                    %w 
                         Weekday number (Sunday = 0).
                    %W 
                         Week of year (00 - 52), Monday is the first day of
                         the week.
                    %x 
                         Locale specific date format.
                    %X 
                         Locale specific time format.
                    %y 
                         Year without century (00 - 99).
                    %Y 
                         Year with century (e.g. 1990)
                    %Z 
                         Time zone name.
                         In addition, the following field  descriptors  may
                         be supported on some systems (e.g.  Unix  but  not
                         Windows): 
                              %D 
                                   Date as %m/%d/%y.
                              %e 
                                   Day of month (1 - 31), no leading zeros.
                                    
                              %h 
                                   Abbreviated month name.
                              %n 
                                   Insert a newline.
                              %r 
                                   Time as %I:%M:%S %p.
                              %R 
                                   Time as %H:%M.
                              %t 
                                   Insert a tab.
                              %T 
                                   Time as %H:%M:%S.
                         If the -format  argument  is  not  specified,  the
                         format string "%a %b %d %H:%M:%S %Z %Y"  is  used.
                         If the -gmt argument is present the next  argument
                         must be a boolean which if true specifies that the
                         time will be formatted as Greenwich Mean Time.  If
                         false then the local  timezone  will  be  used  as
                         defined by the operating environment.

          clock scan dateString ?-base clockVal? ?-gmt boolean?
               Convert dateString to an  integer  clock  value  (see  clock
               seconds). This command can parse and convert  virtually  any
               standard date and/or time string, which can include standard
               time zone mnemonics.  If  only  a  time  is  specified,  the
               current date is assumed. If the string does  not  contain  a
               time zone mnemonic, the local time zone is  assumed,  unless
               the -gmt argument is true, in which case the clock value  is
               calculated assuming that the specified time is  relative  to
               Greenwich Mean Time. -gmt, if specified,  affects  only  the
               computed time value; it does not impact  the  interpretation
               of -base.
               If the -base flag is specified,  the  next  argument  should
               contain an integer clock value. Only the date in this  value
               is used, not the time. This is useful  for  determining  the
               time on a specific day or    doing    other    date-relative
               conversions. 
               The dateString consists of zero or  more  specifications  of
               the following form:
                    time 
                         A time of day, which is of the form:  hh?:mm?:ss??
                         ?meridian? ?zone? or hhmm ?meridian? ?zone?. If no
                         meridian is specified,  hh  is  interpreted  on  a
                         24-hour clock.
                    date 
                         A specific month and day with optional  year.  The
                         acceptable formats are mm/dd?/yy?, monthname dd ?,
                         yy?, dd monthname  ?yy?,  day,  dd  monthname  yy,
                         ?CC?yymmdd, ?CC?yy-mm-dd, dd-monthname-?CC?yy. The
                         default year is the current year. If the  year  is
                         less  than  100,  we  treat  the  years  00-68  as
                         2000-2068 and the years 69-99  as  1969-1999.  Not
                         all platforms can represent the years 38-70, so an
                         error may result if these years are used.
                    ISO 8601 point-in-time
                         An ISO 8601 point-in-time specification,  such  as
                         CCyymmddThhmmss, where T is   the    literal    T,
                         CCyymmdd hhmmss, or CCyymmddThh:mm:ss.
                    relative time
                         A specification relative to the current time.  The
                         format is number unit acceptable units  are  year,
                         fortnight, month,  week,  day,  hour,  minute  (or
                         min),  and  second  (or  sec).  The  unit  can  be
                         specified as a singular or plural, as in 3  weeks.
                         These modifiers may also be  specified:  tomorrow,
                         yesterday, today, now, last, this, next, ago.
                         The actual date is  calculated  according  to  the
                         following steps. First, any absolute  date  and/or
                         time is processed and converted. Using  that  time
                         as the base, day-of-week specifications are added.
                         Next, relative specifications are used. If a  date
                         or day is specified, and no absolute  or  relative
                         time  is  given,  midnight  is  used.  Finally,  a
                         correction is applied so that the correct hour  of
                         the day is produced after  allowing  for  daylight
                         savings time differences and the correct  date  is
                         given when going from the end of a long month to a
                         short month.
                         Daylight savings time correction is  applied  only
                         when the relative time is specified  in  units  of
                         days or more, ie, days, weeks, fortnights,  months
                         or  years.  This  means  that  when  crossing  the
                         daylight savings time boundary, different  results
                         will be given for clock scan  "1  day"  and  clock
                         scan "24 hours": % clock scan "1 day" -base [clock
                         scan 1999-10-31] 941443200 % clock scan "24 hours"
                         -base [clock scan 1999-10-31] 941439600

          clock seconds
               Return the current  date  and  time  as  a  system-dependent
               integer value. The unit of the value is seconds, allowing it
               to be used for relative  time  calculations.  The  value  is
               usually defined as total elapsed time from an ``epoch''. You
               shouldn't assume the value of the epoch.

SEE ALSO
     date, time

KEYWORDS 
     clock, date, time







_________________________________________________________________

NAME
     close - Close an open channel.

SYNOPSIS
	close channelId

_________________________________________________________________

DESCRIPTION 
     Closes the channel given by channelId. ChannelId  must  be  a  channel
     identifier such as the return value from a  previous  open  or  socket
     command. All buffered  output  is  flushed  to  the  channel's  output
     device, any buffered input is discarded, the underlying file or device
     is closed, and channelId becomes unavailable for use.
     If the channel is blocking, the command  does  not  return  until  all
     output is  flushed.  If  the  channel  is  nonblocking  and  there  is
     unflushed output, the channel remains open  and  the  command  returns
     immediately; output will be flushed in the background and the  channel
     will be closed when all the flushing is complete.
     If channelId is a blocking channel for a command pipeline  then  close
     waits for the child processes to complete.
     If the channel  is  shared  between  interpreters,  then  close  makes
     channelId unavailable in the invoking interpreter  but  has  no  other
     effect until all of the sharing interpreters have closed the  channel.
     When the last interpreter in which the channel is  registered  invokes
     close, the cleanup actions  described  above  occur.  See  the  interp
     command for a description of channel sharing.
     Channels are automatically closed when  an  interpreter  is  destroyed
     and when the process exits. Channels are switched to blocking mode, to
     ensure that all output is correctly flushed before the process exits.
     The command returns an empty string, and may generate an error  if  an
     error occurs while flushing output.


SEE ALSO
     file, open, socket, eof

KEYWORDS 
     blocking, channel, close, nonblocking






_________________________________________________________________

NAME
     concat - Join lists together

SYNOPSIS
	concat ?arg arg ...?

_________________________________________________________________

DESCRIPTION 
     This command treats each argument as a list and concatenates them into
     a single list. It also eliminates leading and trailing spaces  in  the
     arg's and adds a single separator space between arg's. It permits  any
     number of arguments. For example, the command concat a b {c d e} {f {g
     h}} will return a b c d e f {g h} as its result.
     If no args are supplied, the result is an empty string.


SEE ALSO
     append, eval

KEYWORDS 
     concatenate, join, lists






_________________________________________________________________

NAME
     continue - Skip to the next iteration of a loop

SYNOPSIS
	continue

_________________________________________________________________

DESCRIPTION 
     This command is typically invoked inside the body of a looping command
     such as for or foreach or while. It returns a TCL_CONTINUE code, which
     causes a continue exception to occur. The exception causes the current
     script to be aborted out to the  innermost  containing  loop  command,
     which then continues with  the  next  iteration  of  the  loop.  Catch
     exceptions are also handled in a few other  situations,  such  as  the
     catch command and the outermost scripts of procedure bodies.


SEE ALSO
     break, for, foreach, while

KEYWORDS 
     continue, iteration, loop






_________________________________________________________________

NAME
     encoding - Manipulate encodings

SYNOPSIS
	encoding option ?arg arg ...?

INTRODUCTION 
     Strings in Tcl are encoded using 16-bit Unicode characters.  Different
     operating system interfaces or applications may  generate  strings  in
     other encodings such as  Shift-JIS.  The  encoding  command  helps  to
     bridge the gap between Unicode and these other formats.


_________________________________________________________________

DESCRIPTION 
     Performs one of several  encoding  related  operations,  depending  on
     option. The legal options are:
          encoding convertfrom ?encoding? data
               Convert data to Unicode from  the  specified  encoding.  The
               characters in data are treated  as  binary  data  where  the
               lower 8-bits of each character is taken as  a  single  byte.
               The resulting sequence of bytes is treated as  a  string  in
               the specified encoding. If encoding is  not  specified,  the
               current system encoding is used.
          encoding convertto ?encoding? string
               Convert string from Unicode to the specified  encoding.  The
               result is a sequence of bytes that represents the  converted
               string. Each byte is stored in the lower 8-bits of a Unicode
               character. If encoding is not specified, the current  system
               encoding is used.
          encoding names
               Returns a list containing the names of all of the  encodings
               that are currently available.
          encoding system ?encoding?
               Set the system encoding to encoding. If encoding is  omitted
               then the command returns the current  system  encoding.  The
               system encoding is  used  whenever  Tcl  passes  strings  to
               system calls.

EXAMPLE 
     It is common practice to write script files using a text  editor  that
     produces output in the euc-jp encoding,  which  represents  the  ASCII
     characters as singe bytes and Japanese characters as two  bytes.  This
     makes it easy to embed literal strings that  correspond  to  non-ASCII
     characters by simply typing  the  strings  in  place  in  the  script.
     However, because the source  command  always  reads  files  using  the
     ISO8859-1 encoding, Tcl will treat each byte in the file as a separate
     character that maps to the 00  page  in  Unicode.  The  resulting  Tcl
     strings will not contain the expected  Japanese  characters.  Instead,
     they will contain a sequence of Latin-1 characters that correspond  to
     the bytes of the original string. The encoding command can be used  to
     convert this string to the expected Japanese Unicode  characters.  For
     example, set s [encoding convertfrom euc-jp "\xA4\xCF"]  would  return
     the Unicode string "\u306F", which is the Hiragana letter HA.


SEE ALSO
     Tcl_GetEncoding 

KEYWORDS 
     encoding 





_________________________________________________________________

NAME
     eof - Check for end of file condition on channel

SYNOPSIS
	eof channelId

_________________________________________________________________

DESCRIPTION 
     Returns 1 if an end of file condition occurred during the most  recent
     input operation on channelId (such as gets), 0 otherwise.


SEE ALSO
     file, open, close, fblocked

KEYWORDS 
     channel, end of file






_________________________________________________________________

NAME
     error - Generate an error

SYNOPSIS
	error message ?info? ?code?

_________________________________________________________________

DESCRIPTION 
     Returns a TCL_ERROR code, which causes command  interpretation  to  be
     unwound. Message is a string that is returned to  the  application  to
     indicate what went wrong.
     If the info argument is provided and  is  non-empty,  it  is  used  to
     initialize  the  global  variable  errorInfo.  errorInfo  is  used  to
     accumulate a stack trace  of  what  was  in  progress  when  an  error
     occurred; as nested commands unwind, the    Tcl    interpreter    adds
     information to errorInfo. If the info argument is present, it is  used
     to initialize errorInfo and the first increment of unwind  information
     will not be added by the Tcl interpreter. In other words, the  command
     containing the error command will not  appear  in  errorInfo;  in  its
     place will be info. This feature is most useful  in  conjunction  with
     the catch command: if a caught error cannot be  handled  successfully,
     info can be used to return a stack trace reflecting the original point
     of occurrence of the error: catch  {...}    errMsg    set    savedInfo
     $errorInfo ... error $errMsg $savedInfo
     If the code argument is present, then  its  value  is  stored  in  the
     errorCode global  variable.  This  variable  is  intended  to  hold  a
     machine-readable description of the error in    cases    where    such
     information is available; see the tclvars manual page for  information
     on the proper format for the variable. If the  code  argument  is  not
     present, then errorCode is automatically reset to ``NONE'' by the  Tcl
     interpreter as part of processing the error generated by the command.


SEE ALSO
     catch, tclvars

KEYWORDS 
     error, errorCode, errorInfo






_________________________________________________________________

NAME
     eval - Evaluate a Tcl script

SYNOPSIS
	eval arg ?arg ...?

_________________________________________________________________

DESCRIPTION 
     Eval takes one or more arguments, which together comprise a Tcl script
     containing one or more commands. Eval concatenates all  its  arguments
     in the same fashion as the concat  command,  passes  the  concatenated
     string to the Tcl interpreter recursively, and returns the  result  of
     that evaluation (or any error generated by it).


KEYWORDS 
     concatenate, evaluate, script

SEE ALSO
     catch, concat, error, subs, tclvars






_________________________________________________________________

NAME
     exec - Invoke subprocess(es)

SYNOPSIS
	exec ?switches? arg ?arg ...?

_________________________________________________________________

DESCRIPTION 
     This command treats its arguments as the specification of one or  more
     subprocesses to execute. The arguments take the  form  of  a  standard
     shell pipeline where each arg becomes one word of a command, and  each
     distinct command becomes a subprocess.
     If the initial arguments to exec start with - then  they  are  treated
     as command-line switches and are  not    part    of    the    pipeline
     specification. The following switches are currently supported:
          -keepnewline 
               Retains a trailing newline in   the    pipeline's    output.
               Normally a trailing newline will be deleted.
          -- 
               Marks the end of switches. The argument following  this  one
               will be treated as the first arg even if it starts with a -.
                
     If an arg (or pair of arg's) has one  of  the  forms  described  below
     then it is used by exec to control the flow of input and output  among
     the subprocess(es). Such arguments will not  be    passed    to    the
     subprocess(es). In forms such as ``< fileName'' fileName may either be
     in a separate argument from ``<'' or in  the  same  argument  with  no
     intervening space (i.e. ``<fileName'').
          | 
               Separates distinct commands in the  pipeline.  The  standard
               output of the preceding  command  will  be  piped  into  the
               standard input of the next command.
          |& 
               Separates distinct commands in the pipeline.  Both  standard
               output and standard error of the preceding command  will  be
               piped into the standard input of the next command. This form
               of redirection overrides forms such as 2> and >&.
          < fileName
               The file named  by  fileName  is  opened  and  used  as  the
               standard input for the first command in the pipeline.
          <@ fileId
               FileId must be the identifier for an open file, such as  the
               return value from a previous call to open. It is used as the
               standard input for the first command in the pipeline. FileId
               must have been opened for reading.
          << value
               Value is passed to the first command as its standard input.
          > fileName
               Standard output from the last command is redirected  to  the
               file named fileName, overwriting its previous contents.
          2> fileName
               Standard error from all commands in    the    pipeline    is
               redirected to  the  file  named  fileName,  overwriting  its
               previous contents.
          >& fileName
               Both standard output from  the  last  command  and  standard
               error from all commands are redirected  to  the  file  named
               fileName, overwriting its previous contents.
          >> fileName
               Standard output from the last command is redirected  to  the
               file named fileName, appending to it rather than overwriting
               it. 
          2>> fileName
               Standard error from all commands in    the    pipeline    is
               redirected to the  file  named  fileName,  appending  to  it
               rather than overwriting it.
          >>& fileName
               Both standard output from  the  last  command  and  standard
               error from all commands are redirected  to  the  file  named
               fileName, appending to it rather than overwriting it.
          >@ fileId
               FileId must be the identifier for an open file, such as  the
               return value from a previous call to open.  Standard  output
               from the last command is redirected to fileId's file,  which
               must have been opened for writing.
          2>@ fileId
               FileId must be the identifier for an open file, such as  the
               return value from a previous call to  open.  Standard  error
               from all commands in the pipeline is redirected to  fileId's
               file. The file must have been opened for writing.
          >&@ fileId
               FileId must be the identifier for an open file, such as  the
               return value from a previous call  to  open.  Both  standard
               output from the last command and  standard  error  from  all
               commands are redirected to fileId's file. The file must have
               been opened for writing.
     If standard output has not  been  redirected  then  the  exec  command
     returns the standard output from the last command in the pipeline.  If
     any of the commands in the pipeline exit abnormally or are  killed  or
     suspended, then exec will return an error and the error  message  will
     include the pipeline's output followed by  error  messages  describing
     the abnormal terminations; the errorCode   variable    will    contain
     additional information about    the    last    abnormal    termination
     encountered. If any of the commands writes to its standard error  file
     and that standard error isn't redirected, then  exec  will  return  an
     error; the error message will include the pipeline's standard  output,
     followed by messages about abnormal terminations (if any), followed by
     the standard error output.
     If the last character of the result or  error  message  is  a  newline
     then that character is normally  deleted  from  the  result  or  error
     message. This is consistent with other Tcl return values, which  don't
     normally end with newlines. However, if -keepnewline is specified then
     the trailing newline is retained.
     If standard input isn't redirected with  ``<''  or  ``<<''  or  ``<@''
     then the standard input for the first command in the pipeline is taken
     from the application's current standard input.
     If the last arg is  ``&''  then  the  pipeline  will  be  executed  in
     background. In this case the exec command will  return  a  list  whose
     elements are the process identifiers for all of  the  subprocesses  in
     the pipeline. The  standard  output  from  the  last  command  in  the
     pipeline will go to the application's standard  output  if  it  hasn't
     been redirected, and error output from all  of  the  commands  in  the
     pipeline will go to  the  application's  standard  error  file  unless
     redirected. 
     The first  word  in  each  command  is  taken  as  the  command  name;
     tilde-substitution is performed on it, and if the result  contains  no
     slashes then the directories in  the  PATH  environment  variable  are
     searched for an executable by the given name. If the name  contains  a
     slash then it must refer to an executable reachable from  the  current
     directory. No ``glob'' expansion or other shell-like substitutions are
     performed on the arguments to commands.


PORTABILITY ISSUES
          Windows (all versions)
               Reading from or writing to a socket, using the ``@  fileId''
               notation, does not work.  When  reading  from  a  socket,  a
               16-bit DOS application will hang and  a  32-bit  application
               will return immediately with end-of-file. When  either  type
               of application  writes  to  a  socket,  the  information  is
               instead sent to the  console,  if  one  is  present,  or  is
               discarded. 
               The Tk console text widget does not  provide  real  standard
               IO capabilities. Under Tk, when  redirecting  from  standard
               input, all applications will see an  immediate  end-of-file;
               information redirected to standard output or standard  error
               will be discarded.
               Either forward or backward  slashes  are  accepted  as  path
               separators for arguments to Tcl commands. When executing  an
               application, the path name specified for the application may
               also contain forward or backward slashes as path separators.
               Bear in mind, however, that most Windows applications accept
               arguments with forward slashes only as option delimiters and
               backslashes only in paths. Any arguments to  an  application
               that specify a path  name  with  forward  slashes  will  not
               automatically be converted to use the  backslash  character.
               If an argument contains forward slashes    as    the    path
               separator, it may or may not be recognized as a  path  name,
               depending on the program.
               Additionally, when calling  a  16-bit  DOS  or  Windows  3.X
               application, all path names must  use  the  short,  cryptic,
               path format (e.g., using   ``applba~1.def''    instead    of
               ``applbakery.default''). 
               Two or more forward or backward slashes in a row in  a  path
               refer to a network path. For example, a simple concatenation
               of the root    directory    c:/    with    a    subdirectory
               /windows/system will yield c://windows/system  (two  slashes
               together), which refers to the mount point called system  on
               the machine called windows (and the c:/ is ignored), and  is
               not  equivalent  to  c:/windows/system,  which  describes  a
               directory on the current computer.  The  file  join  command
               should be used to concatenate path components.
          Windows NT
               When  attempting  to  execute  an  application,  exec  first
               searches for the name as it was specified. Then,  in  order,
               .com, .exe,  and  .bat  are  appended  to  the  end  of  the
               specified name and it searches for the  longer  name.  If  a
               directory name was not specified as part of the  application
               name, the following directories are  automatically  searched
               in order when attempting to locate the application:
                         The directory from which the  Tcl  executable  was
                         loaded. The  current  directory.  The  Windows  NT
                         32-bit system directory.  The  Windows  NT  16-bit
                         system directory. The Windows NT  home  directory.
                         The directories listed in the path.

               In order to execute the shell builtin commands like dir  and
               copy, the caller must prepend ``cmd.exe /c '' to the desired
               command. 
          Windows 95
               When  attempting  to  execute  an  application,  exec  first
               searches for the name as it was specified. Then,  in  order,
               .com, .exe,  and  .bat  are  appended  to  the  end  of  the
               specified name and it searches for the  longer  name.  If  a
               directory name was not specified as part of the  application
               name, the following directories are  automatically  searched
               in order when attempting to locate the application:
                         The directory from which the  Tcl  executable  was
                         loaded. The  current  directory.  The  Windows  95
                         system directory. The Windows 95  home  directory.
                         The directories listed in the path.

               In order to execute the shell builtin commands like dir  and
               copy, the caller must prepend ``command.com  /c  ''  to  the
               desired command.
               Once a 16-bit DOS application has read standard  input  from
               a console and then quit, all  subsequently  run  16-bit  DOS
               applications will see the standard input as already  closed.
               32-bit applications do not have this problem  and  will  run
               correctly, even after a 16-bit DOS application  thinks  that
               standard input is closed. There is no known  workaround  for
               this bug at this time.
               Redirection between the NUL:    device    and    a    16-bit
               application does not  always  work.  When  redirecting  from
               NUL:,  some  applications  may  hang,  others  will  get  an
               infinite stream of ``0x01'' bytes, and  some  will  actually
               correctly get an immediate end-of-file; the  behavior  seems
               to depend  upon  something  compiled  into  the  application
               itself. When redirecting greater than 4K or so to NUL:, some
               applications will hang. The above  problems  do  not  happen
               with 32-bit applications.
               All DOS  16-bit  applications  are  run  synchronously.  All
               standard input from a pipe to a 16-bit  DOS  application  is
               collected into a temporary file; the other end of  the  pipe
               must be closed before  the  16-bit  DOS  application  begins
               executing. All standard output or error from  a  16-bit  DOS
               application to a pipe is collected into temporary files; the
               application must terminate before the  temporary  files  are
               redirected to the next stage of the pipeline. This is due to
               a workaround for a Windows 95 bug in the  implementation  of
               pipes, and is how the standard Windows 95 DOS shell  handles
               pipes itself.
               Certain applications, such as  command.com,  should  not  be
               executed interactively. Applications which  directly  access
               the console window, rather than reading from their  standard
               input and writing to their standard output  may  fail,  hang
               Tcl, or even hang the system if their  own  private  console
               window is not available to them.
          Macintosh 
               The exec command is not implemented and does not exist under
               Macintosh. 
          Unix 
               The exec command is fully functional and works as described.
                

SEE ALSO
     error, open

KEYWORDS 
     execute, pipeline, redirection, subprocess






_________________________________________________________________

NAME
     exit - End the application

SYNOPSIS
	exit ?returnCode?

_________________________________________________________________

DESCRIPTION 
     Terminate the process, returning returnCode to the system as the  exit
     status. If returnCode isn't specified then it defaults to 0.


SEE ALSO
     exec, tclvars

KEYWORDS 
     exit, process






_________________________________________________________________

NAME
     expr - Evaluate an expression

SYNOPSIS
	expr arg ?arg arg ...?

_________________________________________________________________

DESCRIPTION 
     Concatenates arg's (adding separator spaces between  them),  evaluates
     the result as a Tcl expression, and returns the value.  The  operators
     permitted in Tcl expressions are a subset of the  operators  permitted
     in C expressions, and they have the same meaning and precedence as the
     corresponding C operators. Expressions  almost  always  yield  numeric
     results (integer or floating-point  values).    For    example,    the
     expression expr 8.2 + 6 evaluates to 14.2. Tcl expressions differ from
     C expressions in the  way  that  operands  are  specified.  Also,  Tcl
     expressions support non-numeric operands and string comparisons.

OPERANDS 
     A Tcl expression consists of a combination of operands, operators, and
     parentheses.  White  space  may  be  used  between  the  operands  and
     operators and parentheses; it is  ignored    by    the    expression's
     instructions. Where possible,  operands  are  interpreted  as  integer
     values. Integer values may be specified in decimal (the normal  case),
     in octal (if  the  first  character  of  the  operand  is  0),  or  in
     hexadecimal (if the first two characters of the operand are 0x). If an
     operand does not have one of the integer formats given above, then  it
     is treated as a floating-point number    if    that    is    possible.
     Floating-point numbers may be specified in any of the ways accepted by
     an ANSI-compliant C compiler (except that the f, F, l, and L  suffixes
     will not be permitted in most installations). For example, all of  the
     following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. If
     no numeric interpretation is possible, then an operand is  left  as  a
     string (and only a limited set of operators may be applied to it).
     Operands may be specified in any of the following ways:
          [1] 
               As an numeric value, either integer or floating-point.
          [2] 
               As a Tcl variable, using standard $ notation. The variable's
               value will be used as the operand.
          [3] 
               As a string enclosed in double-quotes. The expression parser
               will perform backslash, variable, and command  substitutions
               on the information between the quotes, and use the resulting
               value as the operand
          [4] 
               As a string enclosed in braces. The characters  between  the
               open brace and matching close brace  will  be  used  as  the
               operand without any substitutions.
          [5] 
               As a Tcl command enclosed in brackets. The command  will  be
               executed and its result will be used as the operand.
          [6] 
               As a mathematical function whose arguments have any  of  the
               above forms for operands, such as sin($x). See below  for  a
               list of defined functions.
     Where substitutions occur above (e.g.  inside  quoted  strings),  they
     are performed by the expression's instructions. However, an additional
     layer of substitution may already have been performed by  the  command
     parser before the expression processor was called. As discussed below,
     it is usually best to enclose expressions in  braces  to  prevent  the
     command parser from performing substitutions on the contents.
     For some examples of simple expressions, suppose the  variable  a  has
     the value 3 and the variable b has the value 6. Then  the  command  on
     the left side of each of the lines below will produce the value on the
     right side of the line: expr 3.1 + $a 6.1 expr 2 +  "$a.$b"  5.6  expr
     4*[llength "6 2"] 8 expr {{word one} < "word $a"} 0

OPERATORS 
     The valid operators are listed below, grouped in decreasing  order  of
     precedence: 
          - + ~ !
               Unary minus, unary plus, bit-wise NOT, logical NOT. None  of
               these operands  may  be  applied  to  string  operands,  and
               bit-wise NOT may be applied only to integers.
          * / %
               Multiply, divide, remainder. None of these operands  may  be
               applied to string operands, and  remainder  may  be  applied
               only to integers. The remainder will always  have  the  same
               sign as the divisor and an absolute value smaller  than  the
               divisor. 
          + -
               Add and subtract. Valid for any numeric operands.
          << >>
               Left and right shift. Valid for  integer  operands  only.  A
               right shift always propagates the sign bit.
          < > <= >=
               Boolean less, greater, less than or equal, and greater  than
               or equal. Each operator produces 1 if the condition is true,
               0 otherwise. These operators may be applied  to  strings  as
               well as numeric operands, in which case string comparison is
               used. 
          == !=
               Boolean equal  and  not  equal.  Each  operator  produces  a
               zero/one result. Valid for all operand types.
          eq ne
               Boolean string equal and string  not  equal.  Each  operator
               produces a zero/one result.   The    operand    types    are
               interpreted only as strings.
          & 
               Bit-wise AND. Valid for integer operands only.
          ^ 
               Bit-wise exclusive OR. Valid for integer operands only.
          | 
               Bit-wise OR. Valid for integer operands only.
          && 
               Logical AND. Produces  a  1  result  if  both  operands  are
               non-zero, 0 otherwise. Valid for   boolean    and    numeric
               (integers or floating-point) operands only.
          || 
               Logical OR. Produces a 0 result if both operands are zero, 1
               otherwise.  Valid  for  boolean  and  numeric  (integers  or
               floating-point) operands only.
          x?y:z 
               If-then-else, as in C. If x evaluates to non-zero, then  the
               result is the value of y. Otherwise the result is the  value
               of z. The x operand must have a numeric value.
     See the C manual for more details on  the  results  produced  by  each
     operator. All of the binary operators group left-to-right  within  the
     same precedence level. For example, the command expr 4*2 <  7  returns
     0. 
     The &&, ||, and ?: operators have ``lazy evaluation'', just as  in  C,
     which means that operands are not evaluated if they are not needed  to
     determine the outcome. For example, in the command expr {$v  ?  [a]  :
     [b]} only one of [a] or [b] will actually be evaluated,  depending  on
     the value of $v. Note, however, that this is only true if  the  entire
     expression is enclosed  in  braces;  otherwise  the  Tcl  parser  will
     evaluate both [a] and [b] before invoking the expr command.

MATH FUNCTIONS
     Tcl supports the following mathematical functions in expressions:  abs
     cosh log sqrt acos double log10 srand asin exp pow tan atan floor rand
     tanh atan2 fmod round ceil hypot sin cos int sinh
          abs(arg) 
               Returns the absolute value of arg. Arg may be either integer
               or floating-point, and the result is returned  in  the  same
               form. 
          acos(arg) 
               Returns the arc cosine of arg, in the range [0,pi]  radians.
               Arg should be in the range [-1,1].
          asin(arg) 
               Returns the arc sine  of  arg,  in  the  range  [-pi/2,pi/2]
               radians. Arg should be in the range [-1,1].
          atan(arg) 
               Returns the arc tangent of arg, in  the  range  [-pi/2,pi/2]
               radians. 
          atan2(x, y)
               Returns the arc  tangent  of  y/x,  in  the  range  [-pi,pi]
               radians. x and y cannot both be 0.
          ceil(arg) 
               Returns the smallest integer value not less than arg.
          cos(arg) 
               Returns the cosine of arg, measured in radians.
          cosh(arg) 
               Returns the hyperbolic cosine of arg. If  the  result  would
               cause an overflow, an error is returned.
          double(arg) 
               If arg is a floating value, returns arg, otherwise  converts
               arg to floating and returns the converted value.
          exp(arg) 
               Returns the exponential of arg, defined as  e**arg.  If  the
               result would cause an overflow, an error is returned.
          floor(arg) 
               Returns the largest integral value not greater than arg.
          fmod(x, y)
               Returns the floating-point remainder of the division of x by
               y. If y is 0, an error is returned.
          hypot(x, y)
               Computes the length of  the  hypotenuse  of  a  right-angled
               triangle (x*x+y*y).
          int(arg) 
               If arg is an integer value, returns arg, otherwise  converts
               arg to integer  by  truncation  and  returns  the  converted
               value. 
          log(arg) 
               Returns the natural logarithm of arg. Arg must be a positive
               value. 
          log10(arg) 
               Returns the base 10 logarithm of arg. Arg must be a positive
               value. 
          pow(x, y)
               Computes the value of x raised to  the  power  y.  If  x  is
               negative, y must be an integer value.
          rand() 
               Returns a floating point number from zero to just less  than
               one or, in mathematical terms, the  range  [0,1).  The  seed
               comes from the internal clock of the machine or may  be  set
               manual with the srand function.
          round(arg) 
               If arg is an integer value, returns arg, otherwise  converts
               arg to integer by rounding and returns the converted value.
          sin(arg) 
               Returns the sine of arg, measured in radians.
          sinh(arg) 
               Returns the hyperbolic sine of  arg.  If  the  result  would
               cause an overflow, an error is returned.
          sqrt(arg) 
               Returns the square root of arg. Arg must be non-negative.
          srand(arg) 
               The arg, which must be an integer, is used to reset the seed
               for the random number generator. Returns  the  first  random
               number from that seed. Each interpreter has it's own seed.
          tan(arg) 
               Returns the tangent of arg, measured in radians.
          tanh(arg) 
               Returns the hyperbolic tangent of arg.
     In addition to these predefined  functions,  applications  may  define
     additional functions using Tcl_CreateMathFunc().

TYPES, OVERFLOW, AND PRECISION
     All internal computations involving integers are done with the C  type
     long, and all internal computations involving floating-point are  done
     with the C type double. When converting a  string  to  floating-point,
     exponent overflow  is  detected  and  results  in  a  Tcl  error.  For
     conversion to integer from string, detection of  overflow  depends  on
     the behavior of some routines in the local C library, so it should  be
     regarded as unreliable. In any case, integer  overflow  and  underflow
     are generally not detected reliably    for    intermediate    results.
     Floating-point overflow and  underflow  are  detected  to  the  degree
     supported by the hardware, which is generally pretty reliable.
     Conversion among internal   representations        for        integer,
     floating-point, and string operands is done automatically  as  needed.
     For arithmetic computations,  integers    are    used    until    some
     floating-point number is introduced,  after  which  floating-point  is
     used. For example, expr 5 / 4 returns 1, while expr 5 / 4.0 expr 5 / (
     [string length "abcd"] + 0.0 ) both return 1.25. Floating-point values
     are always returned with a ``.'' or an e so that they  will  not  look
     like integer values. For example, expr 20.0/5.0 returns 4.0, not 4.


STRING OPERATIONS
     String values may be used as operands  of  the  comparison  operators,
     although the expression evaluator tries to do comparisons  as  integer
     or floating-point when it can, except in the case of  the  eq  and  ne
     operators. If one of the operands of a comparison is a string and  the
     other has a numeric value, the numeric operand is converted back to  a
     string using the C sprintf format specifier %d for integers and %g for
     floating-point values. For example, the commands expr {"0x03"  >  "2"}
     expr {"0y" < "0x12"} both return 1. The first comparison is done using
     integer comparison, and the second is  done  using  string  comparison
     after the second operand is converted to the  string  18.  Because  of
     Tcl's tendency to treat values as numbers whenever possible, it  isn't
     generally a good idea to use operators like == when  you  really  want
     string comparison and the values of the operands could  be  arbitrary;
     it's better in these cases to use the  eq  or  ne  operators,  or  the
     string command instead.


PERFORMANCE CONSIDERATIONS
     Enclose expressions in braces for the  best  speed  and  the  smallest
     storage  requirements.  This  allows  the  Tcl  bytecode  compiler  to
     generate the best code.
     As mentioned above, expressions are substituted  twice:  once  by  the
     Tcl parser and once by the expr command. For example, the commands set
     a 3 set b {$a + 2} expr $b*4 return 11, not a multiple of 4.  This  is
     because the Tcl parser will first substitute $a + 2 for  the  variable
     b, then the expr command will evaluate the expression $a + 2*4.
     Most expressions do not  require  a  second  round  of  substitutions.
     Either they are enclosed in braces or,  if  not,  their  variable  and
     command substitutions yield numbers or strings that  don't  themselves
     require substitutions. However, because  a  few  unbraced  expressions
     need two rounds of substitutions,  the  bytecode  compiler  must  emit
     additional instructions to handle this situation. The  most  expensive
     code  is  required  for  unbraced  expressions  that  contain  command
     substitutions. These expressions must be implemented by generating new
     code each time the expression is executed.


SEE ALSO
     array, string, Tcl

KEYWORDS 
     arithmetic, boolean, compare, expression, fuzzy comparison






_________________________________________________________________

NAME
     fblocked -  Test  whether  the  last  input  operation  exhausted  all
     available input

SYNOPSIS
	fblocked channelId

_________________________________________________________________

DESCRIPTION 
     The fblocked command returns 1 if the most recent input  operation  on
     channelId returned less information than   requested    because    all
     available input was exhausted. For example, if gets  is  invoked  when
     there are only three characters available for input and no end-of-line
     sequence, gets returns an  empty  string  and  a  subsequent  call  to
     fblocked will return 1.

SEE ALSO
     gets, open, read

KEYWORDS 
     blocking, nonblocking





_________________________________________________________________

NAME
     fconfigure - Set and get options on a channel

SYNOPSIS
	fconfigure channelId
	fconfigure channelId name
	fconfigure channelId name value ?name value ...?

_________________________________________________________________

DESCRIPTION 
     The fconfigure  command  sets  and  retrieves  options  for  channels.
     ChannelId identifies the channel for which to set or query an  option.
     If no name or value arguments are supplied, the command returns a list
     containing alternating option names and values  for  the  channel.  If
     name is supplied but no value then the  command  returns  the  current
     value of the given option. If one or more pairs of name and value  are
     supplied, the command sets each of the   named    options    to    the
     corresponding value; in this case the return value is an empty string.
      
     The options  described  below  are  supported  for  all  channels.  In
     addition, each channel type may add options that only it supports. See
     the manual entry for the command that creates each  type  of  channels
     for the options that that  specific  type  of  channel  supports.  For
     example,  see  the  manual  entry  for  the  socket  command  for  its
     additional options.
          -blocking boolean
               The -blocking option determines whether  I/O  operations  on
               the channel can cause the process to block indefinitely. The
               value of the option must be a proper boolean value. Channels
               are normally in blocking mode; if a channel is  placed  into
               nonblocking mode it will affect the operation of  the  gets,
               read, puts, flush, and close commands; see the documentation
               for those commands for details. For nonblocking mode to work
               correctly, the application must be using the Tcl event  loop
               (e.g.  by  calling  Tcl_DoOneEvent  or  invoking  the  vwait
               command). 
          -buffering newValue
               If newValue is full then the I/O system will  buffer  output
               until its internal buffer is full or until the flush command
               is invoked. If newValue is line, then the  I/O  system  will
               automatically  flush  output  for  the  channel  whenever  a
               newline character is output. If newValue is  none,  the  I/O
               system will flush  automatically    after    every    output
               operation. The default is for -buffering to be set  to  full
               except for channels that connect to  terminal-like  devices;
               for these channels  the    initial    setting    is    line.
               Additionally, stdin and stdout are intially set to line, and
               stderr is set to none.
          -buffersize newSize
               Newvalue must be an integer; its value is used  to  set  the
               size of buffers, in bytes, subsequently allocated  for  this
               channel to store input or output. Newvalue must  be  between
               ten and one million, allowing buffers of ten to one  million
               bytes in size.
          -encoding name
               This option is used to specify the encoding of the  channel,
               so that the data can be converted to and  from  Unicode  for
               use  in  Tcl.  For  instance,  in  order  for  Tcl  to  read
               characters from a Japanese file  in  shiftjis  and  properly
               process and display the contents, the encoding would be  set
               to shiftjis. Thereafter, when reading from the channel,  the
               bytes in the Japanese file would be converted to Unicode  as
               they are read. Writing is also supported -  as  Tcl  strings
               are written  to  the  channel  they  will  automatically  be
               converted to the specified encoding on output.
               If a file contains pure binary data (for  instance,  a  JPEG
               image), the encoding for the channel should be configured to
               be binary. Tcl will then assign  no  interpretation  to  the
               data in the file and simply read or write raw bytes. The Tcl
               binary command can be used to manipulate this  byte-oriented
               data. 
               The default encoding for newly opened channels is  the  same
               platform- and  locale-dependent  system  encoding  used  for
               interfacing with the operating system.
          -eofchar char
          -eofchar {inChar outChar}
               This option supports DOS file  systems  that  use  Control-z
               (\x1a) as an end of file marker. If char  is  not  an  empty
               string, then this character signals end-of-file when  it  is
               encountered during input. For  output,    the    end-of-file
               character is output when the channel is closed. If  char  is
               the empty string, then there  is  no  special  end  of  file
               character marker. For  read-write  channels,  a  two-element
               list specifies the end of file marker for input and  output,
               respectively. As a convenience, when setting the end-of-file
               character for a read-write channel you can specify a  single
               value that will apply to  both  reading  and  writing.  When
               querying the end-of-file character of a read-write  channel,
               a two-element list will  always  be  returned.  The  default
               value for -eofchar is the empty string in all  cases  except
               for files under  Windows.  In  that  case  the  -eofchar  is
               Control-z (\x1a)  for  reading  and  the  empty  string  for
               writing. 
          -translation mode
          -translation {inMode outMode}
               In Tcl scripts the end of a line is always represented using
               a single newline character (\n). However,  in  actual  files
               and devices the end of a line may be represented differently
               on different platforms, or even for different devices on the
               same platform. For example, under UNIX newlines are used  in
               files, whereas  carriage-return-linefeed    sequences    are
               normally used in network connections. On input  (i.e.,  with
               gets and read) the Tcl I/O system  automatically  translates
               the external end-of-line   representation    into    newline
               characters. Upon output (i.e., with puts),  the  I/O  system
               translates  newlines    to    the    external    end-of-line
               representation. The default translation mode, auto,  handles
               all the common cases  automatically,  but  the  -translation
               option provides  explicit  control  over  the  end  of  line
               translations. 
               The value associated with -translation is a single item  for
               read-only and write-only channels.   The    value    is    a
               two-element list for  read-write    channels;    the    read
               translation mode is the first element of the list,  and  the
               write translation mode is the  second    element.    As    a
               convenience, when setting the translation   mode    for    a
               read-write channel you can specify a single value that  will
               apply  to  both  reading  and  writing.  When  querying  the
               translation mode of a read-write channel, a two-element list
               will always be returned. The following values are  currently
               supported: 
                    auto 
                         As the input translation mode, auto treats any  of
                         newline (lf), carriage return  (cr),  or  carriage
                         return followed by a newline (crlf) as the end  of
                         line   representation.    The    end    of    line
                         representation can even change from  line-to-line,
                         and all cases are translated to a newline. As  the
                         output translation mode, auto chooses  a  platform
                         specific representation; for  sockets    on    all
                         platforms Tcl chooses crlf, for all Unix  flavors,
                         it chooses  lf,  for  the  Macintosh  platform  it
                         chooses cr and for the various flavors of  Windows
                         it chooses crlf.  The    default    setting    for
                         -translation is auto for both input and output.
                    binary 
                         No end-of-line translations are performed. This is
                         nearly  identical  to  lf  mode,  except  that  in
                         addition binary mode  also  sets  the  end-of-file
                         character to the empty string (which disables  it)
                         and sets the encoding to  binary  (which  disables
                         encoding filtering). See  the    description    of
                         -eofchar and -encoding for more information.
                    cr 
                         The end of a line in the underlying file or device
                         is represented by a   single    carriage    return
                         character. As the input translation mode, cr  mode
                         converts carriage returns to  newline  characters.
                         As the output translation mode, cr mode translates
                         newline characters to carriage returns. This  mode
                         is typically used on Macintosh platforms.
                    crlf 
                         The end of a line in the underlying file or device
                         is represented  by  a  carriage  return  character
                         followed by a linefeed  character.  As  the  input
                         translation mode, crlf        mode        converts
                         carriage-return-linefeed sequences   to    newline
                         characters. As the output translation  mode,  crlf
                         mode translates newline       characters        to
                         carriage-return-linefeed sequences. This  mode  is
                         typically used on Windows  platforms    and    for
                         network connections.
                    lf 
                         The end of a line in the underlying file or device
                         is represented  by  a  single  newline  (linefeed)
                         character. In  this  mode  no  translations  occur
                         during  either  input  or  output.  This  mode  is
                         typically used on UNIX platforms.

SEE ALSO
     close, flush, gets, puts, read, socket

KEYWORDS 
     blocking, buffering, carriage return, end of line, flushing, linemode,
     newline, nonblocking, platform, translation,  encoding,  filter,  byte
     array, binary





_________________________________________________________________

NAME
     fcopy - Copy data from one channel to another.

SYNOPSIS
	fcopy inchan outchan ?-size size? ?-command callback?

_________________________________________________________________

DESCRIPTION 
     The fcopy command copies data from one I/O channel, inchan to  another
     I/O channel, outchan. The fcopy command leverages the buffering in the
     Tcl I/O system to avoid extra copies and to avoid buffering  too  much
     data in main memory when copying large files to slow destinations like
     network sockets.
     The fcopy command transfers data from inchan  until  end  of  file  or
     size bytes have been transferred. If no -size argument is given,  then
     the copy goes until end of file. All the  data  read  from  inchan  is
     copied to outchan. Without the -command option, fcopy blocks until the
     copy is complete and returns the number of bytes written to outchan.
     The -command argument makes fcopy work  in  the  background.  In  this
     case it returns immediately and the callback is invoked later when the
     copy completes. The callback is called  with  one  or  two  additional
     arguments that indicates how many bytes were written to outchan. If an
     error occurred during the background copy, the second argument is  the
     error string associated with the error. With a background copy, it  is
     not necessary to put inchan or outchan  into  non-blocking  mode;  the
     fcopy command  takes  care  of  that  automatically.  However,  it  is
     necessary to enter the event loop by using the  vwait  command  or  by
     using Tk.
     You are not allowed to do other I/O operations with inchan or  outchan
     during a background fcopy. If either  inchan  or  outchan  get  closed
     while the copy is in progress, the current copy  is  stopped  and  the
     command callback is not made. If  inchan  is  closed,  then  all  data
     already queued for outchan is written out.
     Note that inchan can become readable during  a  background  copy.  You
     should turn off any fileevent handlers during  a  background  copy  so
     those handlers do not interfere with the copy. Any I/O attempted by  a
     fileevent handler will get a "channel busy" error.
     Fcopy translates end-of-line sequences  in    inchan    and    outchan
     according to the -translation  option  for  these  channels.  See  the
     manual entry for fconfigure for details on  the  -translation  option.
     The translations mean that the number of bytes read from inchan can be
     different than the number of bytes written to outchan. Only the number
     of bytes written to outchan is reported, either as the return value of
     a synchronous fcopy  or  as  the  argument  to  the  callback  for  an
     asynchronous fcopy.


EXAMPLE 
     This first example shows how the callback gets passed  the  number  of
     bytes transferred. It also uses vwait to put the application into  the
     event loop. Of course, this simplified example could be  done  without
     the command callback. proc Cleanup {in out bytes {error {}}} {  global
     total set total $bytes close $in close $out if {[string length $error]
     != 0} { # error occurred during the copy } } set in [open $file1]  set
     out [socket $server $port] fcopy $in $out -command [list  Cleanup  $in
     $out] vwait total
     The second example copies in chunks and tests for end of file  in  the
     command callback proc CopyMore {in  out  chunk  bytes  {error  {}}}  {
     global total done incr total $bytes if {([string length $error] !=  0)
     || [eof $in] { set done $total close $in close $out } else { fcopy $in
     $out -command [list CopyMore $in $out $chunk] \ -size $chunk }  }  set
     in [open $file1] set out [socket $server $port]  set  chunk  1024  set
     total 0 fcopy $in $out -command [list CopyMore $in $out $chunk]  -size
     $chunk vwait done

SEE ALSO
     eof, fblocked, fconfigure

KEYWORDS 
     blocking, channel, end  of  line,  end  of  file,  nonblocking,  read,
     translation 






_________________________________________________________________

NAME
     file - Manipulate file names and attributes

SYNOPSIS
	file option name ?arg arg ...?

_________________________________________________________________

DESCRIPTION 
     This command provides several operations on  a    file's    name    or
     attributes. Name is the name of a file; if it  starts  with  a  tilde,
     then tilde substitution is done before executing the command (see  the
     manual entry for filename for details). Option indicates  what  to  do
     with the file name. Any unique abbreviation for option is  acceptable.
     The valid options are:
          file atime name ?time?
               Returns a decimal string giving the time at which file  name
               was last accessed. If time is specified,  it  is  an  access
               time to set for the  file.  The  time  is  measured  in  the
               standard POSIX fashion as seconds from a fixed starting time
               (often January 1, 1970). If the file doesn't  exist  or  its
               access time cannot be  queried  or  set  then  an  error  is
               generated. On Windows,  FAT  file  systems  do  not  support
               access time.
          file attributes name
               file attributes name ?option? file attributes  name  ?option
               value option value...?
                         This subcommand returns or sets platform  specific
                         values associated with  a  file.  The  first  form
                         returns a list of the platform specific flags  and
                         their values. The second form  returns  the  value
                         for the specific option. The third form  sets  one
                         or more of the values. The values are as follows:
                         On Unix, -group gets or sets the  group  name  for
                         the file. A group id can be given to the  command,
                         but it returns a group name. -owner gets  or  sets
                         the user name  of  the  owner  of  the  file.  The
                         command returns the owner name, but the  numerical
                         id can be passed  when    setting    the    owner.
                         -permissions sets or retrieves the octal code that
                         chmod(1) uses. This command does also has  limited
                         support for setting using the symbolic  attributes
                         for     chmod(1),        of        the        form
                         [ugo]?[[+-=][rwxst],[...]],  where        multiple
                         symbolic attributes can  be  separated  by  commas
                         (example:  u+s,go-rw  add  sticky  bit  for  user,
                         remove read and write permissions  for  group  and
                         other). A simplified ls style string, of the  form
                         rwxrwxrwx (must be 9    characters),    is    also
                         supported (example:  rwxr-xr-t  is  equivalent  to
                         01755). 
                         On Windows, -archive gives the value  or  sets  or
                         clears the archive attribute of the file.  -hidden
                         gives the value  or  sets  or  clears  the  hidden
                         attribute of the file. -longname will expand  each
                         path element to its long version.  This  attribute
                         cannot be set. -readonly gives the value  or  sets
                         or clears the  readonly  attribute  of  the  file.
                         -shortname gives a string where every path element
                         is replaced with its short (8.3)  version  of  the
                         name. This attribute cannot be set. -system  gives
                         or sets or clears the value    of    the    system
                         attribute of the file.
                         On Macintosh, -creator gives or  sets  the  Finder
                         creator type of the file. -hidden gives or sets or
                         clears the hidden attribute of the file. -readonly
                         gives or sets or clears the readonly attribute  of
                         the file. Note that directories can only be locked
                         if File Sharing is turned on. -type gives or  sets
                         the Finder file type for the file.

          file channels ?pattern?
               If pattern isn't specified, returns a list of names  of  all
               registered open channels in this interpreter. If pattern  is
               specified, only those names matching pattern  are  returned.
               Matching is determined using the same rules  as  for  string
               match. 
          file copy ?-force? ?--? source target
               file copy ?-force? ?--? source ?source ...? targetDir
                         The first  form  makes  a  copy  of  the  file  or
                         directory source under  the  pathname  target.  If
                         target is an existing directory, then  the  second
                         form is used. The second form makes a copy  inside
                         targetDir of each source file   listed.    If    a
                         directory is  specified  as  a  source,  then  the
                         contents of  the  directory  will  be  recursively
                         copied into targetDir. Existing files will not  be
                         overwritten unless the -force option is specified.
                         Trying to overwrite   a    non-empty    directory,
                         overwrite a directory with a file, or a file  with
                         a directory will all  result  in  errors  even  if
                         -force was specified. Arguments are  processed  in
                         the order specified, halting at the  first  error,
                         if any. A  --  marks  the  end  of  switches;  the
                         argument following the -- will  be  treated  as  a
                         source even if it starts with a -.

          file delete ?-force? ?--? pathname ?pathname ... ?
               Removes the file or directory  specified  by  each  pathname
               argument. Non-empty directories will be removed only if  the
               -force option is specified. Trying to delete a  non-existant
               file  is  not  considered  an  error.  Trying  to  delete  a
               read-only file will cause the file to be  deleted,  even  if
               the -force flags is not specified. Arguments  are  processed
               in the order specified, halting at the first error, if  any.
               A -- marks the end of switches; the argument  following  the
               -- will be treated as a pathname even if it starts with a -.
                
          file dirname name
               Returns a name comprised of all of the  path  components  in
               name excluding the last element. If name is a relative  file
               name and only contains one path element, then returns  ``.''
               (or ``:'' on the  Macintosh).  If  name  refers  to  a  root
               directory, then the root directory is returned. For example,
               file dirname c:/ returns c:/.
               Note that tilde substitution will only be  performed  if  it
               is necessary to complete  the  command.  For  example,  file
               dirname ~/src/foo.c returns ~/src, whereas  file  dirname  ~
               returns /home (or something similar).
          file executable name
               Returns 1 if file name is executable by the current user,  0
               otherwise. 
          file exists name
               Returns 1 if file name  exists  and  the  current  user  has
               search privileges for  the  directories  leading  to  it,  0
               otherwise. 
          file extension name
               Returns all of the characters in name  after  and  including
               the last dot in the last element of name. If there is no dot
               in the last element of name then returns the empty string.
          file isdirectory name
               Returns 1 if file name is a directory, 0 otherwise.
          file isfile name
               Returns 1 if file name is a regular file, 0 otherwise.
          file join name ?name ...?
               Takes one or more file names and combines  them,  using  the
               correct path  separator  for  the  current  platform.  If  a
               particular name is relative, then it will be joined  to  the
               previous file name argument.    Otherwise,    any    earlier
               arguments will be discarded, and joining will  proceed  from
               the current argument. For example, file join a  b  /foo  bar
               returns /foo/bar.
               Note that any of the names can contain separators, and  that
               the result is always canonical for the current  platform:  /
               for Unix and Windows, and : for Macintosh.
          file lstat name varName
               Same as stat option (see below) except uses the lstat kernel
               call instead of stat. This means that if name  refers  to  a
               symbolic link the information returned in varName is for the
               link rather than the file it  refers  to.  On  systems  that
               don't support symbolic links this option behaves exactly the
               same as the stat option.
          file mkdir dir ?dir ...?
               Creates each directory  specified.  For  each  pathname  dir
               specified, this command will create all non-existing  parent
               directories as well as dir itself. If an existing  directory
               is specified, then no  action  is  taken  and  no  error  is
               returned. Trying  to  overwrite  an  existing  file  with  a
               directory will result in an error. Arguments  are  processed
               in the order specified, halting at the first error, if any.
          file mtime name ?time?
               Returns a decimal string giving the time at which file  name
               was last modified. If time is    specified,    it    is    a
               modification time to set for the file  (equivalent  to  Unix
               touch). The time is measured in the standard  POSIX  fashion
               as seconds from a fixed  starting  time  (often  January  1,
               1970). If the file doesn't exist or its modified time cannot
               be queried or set then an error is generated.
          file nativename name
               Returns the platform-specific name  of  the  file.  This  is
               useful if the filename is    needed    to    pass    to    a
               platform-specific  call,  such  as  exec  under  Windows  or
               AppleScript on the Macintosh.
          file owned name
               Returns 1 if file name is  owned  by  the  current  user,  0
               otherwise. 
          file pathtype name
               Returns one of absolute, relative, volumerelative.  If  name
               refers to a specific file on a  specific  volume,  the  path
               type will be absolute. If name refers to a file relative  to
               the current working directory, then the path  type  will  be
               relative. If name refers to a file relative to  the  current
               working directory on a specified volume, or  to  a  specific
               file on the current working volume, then the  file  type  is
               volumerelative. 
          file readable name
               Returns 1 if file name is readable by the  current  user,  0
               otherwise. 
          file readlink name
               Returns the value of the symbolic link given by  name  (i.e.
               the name of the file it points to). If name isn't a symbolic
               link or its value cannot be read, then an error is returned.
               On systems that don't support symbolic links this option  is
               undefined. 
          file rename ?-force? ?--? source target
     file rename ?-force? ?--? source ?source ...? targetDir
          The first form takes the file or directory specified by  pathname
          source and renames it to target, moving the file if the  pathname
          target specifies a name in a different directory. If target is an
          existing directory, then the second form is used. The second form
          moves each source file or directory into the directory targetDir.
          Existing files will not be overwritten unless the  -force  option
          is specified. Trying to overwrite    a    non-empty    directory,
          overwrite a directory with a file, or a  file  with  a  directory
          will all result in errors. Arguments are processed in  the  order
          specified, halting at the first error, if any. A -- marks the end
          of switches; the argument following the -- will be treated  as  a
          source even if it starts with a -.
     file rootname name
          Returns all of the characters in name up to but not including the
          last ``.'' character in the last component of name. If  the  last
          component of name doesn't contain a dot, then returns name.
     file size name
          Returns a decimal string giving the size of file name  in  bytes.
          If the file doesn't exist or its size cannot be queried  then  an
          error is generated.
     file split name
          Returns a list whose elements are the path  components  in  name.
          The first element of the list will have the  same  path  type  as
          name. All other elements will be relative. Path  separators  will
          be discarded unless they are needed ensure  that  an  element  is
          unambiguously  relative.  For  example,  under  Unix  file  split
          /foo/~bar/baz returns / foo  ./~bar  baz  to  ensure  that  later
          commands that use the third component do not attempt  to  perform
          tilde substitution.
     file stat name varName
          Invokes the stat kernel call on name, and uses the variable given
          by varName to hold information returned  from  the  kernel  call.
          VarName is treated  as  an  array  variable,  and  the  following
          elements of that variable are set: atime, ctime, dev,  gid,  ino,
          mode, mtime, nlink, size, type, uid. Each element except type  is
          a decimal string with the value of the corresponding  field  from
          the stat return structure; see the  manual  entry  for  stat  for
          details on the meanings of the values. The type element gives the
          type of the file in the same form returned by  the  command  file
          type. This command returns an empty string.
     file tail name
          Returns all of the characters in name after  the  last  directory
          separator. If name contains no separators then returns name.
     file type name
          Returns a string giving the type of file name, which will be  one
          of file, directory, characterSpecial, blockSpecial,  fifo,  link,
          or socket.
     file volume
          Returns the absolute paths to the volumes mounted on the  system,
          as a proper Tcl list. On the Macintosh, this will be  a  list  of
          the mounted drives, both local and network. N.B.  if  two  drives
          have the same name, they will both appear on the volume list, but
          there is currently no way, from Tcl, to access any but the  first
          of these drives. On UNIX, the command  will  always  return  "/",
          since all filesystems are locally mounted. On  Windows,  it  will
          return a list of the available local drives (e.g. {a:/ c:/}).
     file writable name
          Returns 1 if file  name  is  writable  by  the  current  user,  0
          otherwise. 
PORTABILITY ISSUES
          Unix 
               These commands always operate using the real user and  group
               identifiers, not the effective ones.

SEE ALSO
     filename, open, close, eof, gets, tell, seek, fblocked, flush

KEYWORDS 
     attributes, copy files, delete files,  directory,  file,  move  files,
     name, rename files, stat






_________________________________________________________________

NAME
     fileevent - Execute a  script  when  a  channel  becomes  readable  or
     writable 

SYNOPSIS
	fileevent channelId readable ?script?
	fileevent channelId writable ?script?

_________________________________________________________________

DESCRIPTION 
     This command is used to create  file  event  handlers.  A  file  event
     handler is a binding between a channel and a  script,  such  that  the
     script is evaluated whenever the channel becomes readable or writable.
     File event handlers are  most  commonly  used  to  allow  data  to  be
     received from another process on an event-driven basis,  so  that  the
     receiver can continue to interact with the user while waiting for  the
     data to arrive. If an application invokes gets or read on  a  blocking
     channel when there is no input data available, the process will block;
     until the input data arrives, it will not be  able  to  service  other
     events, so  it  will  appear  to  the  user  to  ``freeze  up''.  With
     fileevent, the process can tell when data is present and  only  invoke
     gets or read when they won't block.
     The channelId argument to fileevent refers to an  open  channel,  such
     as the return value from a previous open or  socket  command.  If  the
     script argument is specified,  then  fileevent  creates  a  new  event
     handler:  script  will  be  evaluated  whenever  the  channel  becomes
     readable or writable (depending on the second argument to  fileevent).
     In this case fileevent returns  an  empty  string.  The  readable  and
     writable event handlers for a file are independent, and may be created
     and deleted separately. However, there may be at most one readable and
     one  writable  handler  for  a  file  at  a  given  time  in  a  given
     interpreter. If fileevent is called when the specified handler already
     exists in the invoking interpreter, the new script  replaces  the  old
     one. 
     If the  script  argument  is  not  specified,  fileevent  returns  the
     current script for channelId, or an empty string if there is none.  If
     the script argument is specified as an empty  string  then  the  event
     handler is deleted, so that no script will be invoked.  A  file  event
     handler is also deleted automatically whenever its channel  is  closed
     or its interpreter is deleted.
     A channel is considered  to  be  readable  if  there  is  unread  data
     available on the underlying device. A channel is also considered to be
     readable if there is unread data in an input  buffer,  except  in  the
     special case where the most recent attempt to read  from  the  channel
     was a gets call that could not find  a  complete  line  in  the  input
     buffer. This feature allows a file to be read a  line  at  a  time  in
     nonblocking mode using events. A channel  is  also  considered  to  be
     readable if an end of file  or  error  condition  is  present  on  the
     underlying file or device. It is important for  script  to  check  for
     these conditions and handle them appropriately; for example, if  there
     is no special check for end of file, an infinite loop may occur  where
     script reads no data, returns, and is immediately invoked again.
     A channel is considered to be writable if at least one  byte  of  data
     can be written to the underlying file or device without  blocking,  or
     if an error condition is present on the underlying file or device.
     Event-driven I/O works best for channels that have  been  placed  into
     nonblocking mode with the fconfigure command. In blocking mode, a puts
     command may block if you give it more data than the underlying file or
     device can accept, and a gets  or  read  command  will  block  if  you
     attempt to read more data than is ready; no events will  be  processed
     while the commands block. In nonblocking mode  puts,  read,  and  gets
     never block. See the documentation for  the  individual  commands  for
     information on how they handle blocking and nonblocking channels.
     The script for a file event is executed at global level  (outside  the
     context of  any  Tcl  procedure)  in  the  interpreter  in  which  the
     fileevent command was invoked. If an error occurs while executing  the
     script then the bgerror mechanism is used  to  report  the  error.  In
     addition, the file event handler is deleted  if  it  ever  returns  an
     error; this is done in order to prevent infinite loops  due  to  buggy
     handlers. 


CREDITS 
     fileevent is based on the addinput command created by Mark Diekhans.


SEE ALSO
     bgerror, fconfigure, gets, puts, read

KEYWORDS 
     asynchronous  I/O,  blocking,  channel,  event  handler,  nonblocking,
     readable, script, writable.






_________________________________________________________________

NAME
     filename - File name conventions supported by Tcl commands

INTRODUCTION 
     All Tcl commands and C procedures that take file  names  as  arguments
     expect the file names to be in one of three forms,  depending  on  the
     current platform. On each platform, Tcl supports  file  names  in  the
     standard forms(s) for that platform. In addition,  on  all  platforms,
     Tcl supports a Unix-like syntax intended to provide a  convenient  way
     of constructing simple file names. However, scripts that are  intended
     to be portable should not assume a particular  form  for  file  names.
     Instead, portable scripts must  use  the  file  split  and  file  join
     commands to manipulate file names (see the file manual entry for  more
     details). 


PATH TYPES
     File names are grouped into three general types based on the  starting
     point for the path used to specify the file: absolute,  relative,  and
     volume-relative. Absolute names are  completely  qualified,  giving  a
     path to the  file  relative  to  a  particular  volume  and  the  root
     directory on that volume. Relative names  are  unqualified,  giving  a
     path to the file relative to   the    current    working    directory.
     Volume-relative names are partially qualified, either giving the  path
     relative to the root directory on the current volume, or  relative  to
     the current directory of  the  specified  volume.  The  file  pathtype
     command can be used to determine the type of a given path.


PATH SYNTAX
     The rules for native names depend on the value  reported  in  the  Tcl
     array element tcl_platform(platform):
          mac 
               On Apple Macintosh systems, Tcl supports two forms  of  path
               names. The  normal  Mac  style  names  use  colons  as  path
               separators. Paths may be  relative  or  absolute,  and  file
               names may contain any character other than colon. A  leading
               colon causes the rest of the path to be interpreted relative
               to the current directory. If a path contains a colon that is
               not at the beginning, then the path  is  interpreted  as  an
               absolute path. Sequences of two or more colons  anywhere  in
               the path are used  to  construct  relative  paths  where  ::
               refers to the parent of the current directory, ::: refers to
               the parent of the parent, and so forth.
               In addition to Macintosh style names, Tcl  also  supports  a
               subset of Unix-like names. If a  path  contains  no  colons,
               then it is interpreted like a Unix path. Slash  is  used  as
               the path separator. The file name . refers  to  the  current
               directory, and ..  refers  to  the  parent  of  the  current
               directory. However,  some  names  like  /  or  /..  have  no
               mapping, and are interpreted as Macintosh names. In general,
               commands that generate  file  names  will  return  Macintosh
               style names, but commands that accept file names  will  take
               both Macintosh and Unix-style names.
               The following examples  illustrate  various  forms  of  path
               names: 
                    : 
                         Relative path to the current folder.
                    MyFile 
                         Relative path  to  a  file  named  MyFile  in  the
                         current folder.
                    MyDisk:MyFile 
                         Absolute path to a file named MyFile on the device
                         named MyDisk.
                    :MyDir:MyFile 
                         Relative path to a file name MyFile  in  a  folder
                         named MyDir in the current folder.
                    ::MyFile 
                         Relative path to a file named MyFile in the folder
                         above the current folder.
                    :::MyFile 
                         Relative path to a file named MyFile in the folder
                         two levels above the current folder.
                    /MyDisk/MyFile 
                         Absolute path to a file named MyFile on the device
                         named MyDisk.
                    ../MyFile 
                         Relative path to a file named MyFile in the folder
                         above the current folder.
          unix 
               On Unix platforms, Tcl uses path names where the  components
               are separated by slashes. Path  names  may  be  relative  or
               absolute, and file names may  contain  any  character  other
               than slash. The file names . and .. are special and refer to
               the current directory and the parent    of    the    current
               directory respectively. Multiple adjacent  slash  characters
               are interpreted as a single   separator.    The    following
               examples illustrate various forms of path names:
                    / 
                         Absolute path to the root directory.
                    /etc/passwd 
                         Absolute path to the  file  named  passwd  in  the
                         directory etc in the root directory.
                    . 
                         Relative path to the current directory.
                    foo 
                         Relative path to  the  file  foo  in  the  current
                         directory. 
                    foo/bar 
                         Relative path to the file bar in the directory foo
                         in the current directory.
                    ../foo 
                         Relative path to the file  foo  in  the  directory
                         above the current directory.
          windows 
               On Microsoft Windows   platforms,    Tcl    supports    both
               drive-relative and UNC style names. Both / and \ may be used
               as directory separators  in    either    type    of    name.
               Drive-relative names consist of an optional drive  specifier
               followed by an absolute or relative path. UNC  paths  follow
               the general form \\servername\sharename\path\file.  In  both
               forms, the file names . and .. are special and refer to  the
               current directory and the parent of  the  current  directory
               respectively.  The  following  examples  illustrate  various
               forms of path names:
                    \\Host\share/file 
                         Absolute UNC path to a file  called  file  in  the
                         root directory of the export point  share  on  the
                         host Host.
                    c:foo 
                         Volume-relative path to a file foo in the  current
                         directory on drive c.
                    c:/foo 
                         Absolute path to a file foo in the root  directory
                         of drive c.
                    foo\bar 
                         Relative path to a file bar in the  foo  directory
                         in the current directory on the current volume.
                    \foo 
                         Volume-relative path to a file  foo  in  the  root
                         directory of the current volume.
TILDE SUBSTITUTION
     In addition to the file name rules described above, Tcl also  supports
     csh-style tilde substitution. If a file name starts with a tilde, then
     the file name will be interpreted as if the first element is  replaced
     with the location of the home directory for the  given  user.  If  the
     tilde is followed immediately by a  separator,    then    the    $HOME
     environment variable is substituted. Otherwise the characters  between
     the tilde and the next separator are taken as a user  name,  which  is
     used to retrieve the user's home directory for substitution.
     The Macintosh and Windows platforms do not support tilde  substitution
     when a user name follows the tilde. On these  platforms,  attempts  to
     use a tilde followed by a user name will generate an error. File names
     that have a tilde without a user name will be  substituted  using  the
     $HOME environment variable, just like for Unix.


PORTABILITY ISSUES
     Not all file systems are case sensitive, so scripts should avoid  code
     that depends on the case of characters in a file  name.  In  addition,
     the character sets allowed on different devices may differ, so scripts
     should choose file names that do not contain special characters  like:
     <>:"/\|. The safest approach is to    use    names    consisting    of
     alphanumeric characters only. Also  Windows  3.1  only  supports  file
     names with a root of no more than 8 characters and an extension of  no
     more than 3 characters.


KEYWORDS 
     current directory, absolute file    name,    relative    file    name,
     volume-relative file name, portability

SEE ALSO
     file, glob





_________________________________________________________________

NAME
     flush - Flush buffered output for a channel

SYNOPSIS
	flush channelId

_________________________________________________________________

DESCRIPTION 
     Flushes any output that has been  buffered  for  channelId.  ChannelId
     must be a channel identifier such as returned by a  previous  open  or
     socket command, and it must have  been  opened  for  writing.  If  the
     channel is in blocking mode the command does not return until all  the
     buffered output has been flushed to the channel. If the channel is  in
     nonblocking mode, the command may return before  all  buffered  output
     has been flushed; the remainder will be flushed in the  background  as
     fast as the underlying file or device is able to absorb it.


SEE ALSO
     file, open, socket

KEYWORDS 
     blocking, buffer, channel, flush, nonblocking, output






_________________________________________________________________

NAME
     for - ``For'' loop

SYNOPSIS
	for start test next body

_________________________________________________________________

DESCRIPTION 
     For is a looping command, similar in structure to the C for statement.
     The start, next, and body arguments must be Tcl command  strings,  and
     test is an expression string. The for command first  invokes  the  Tcl
     interpreter to execute start. Then it repeatedly evaluates test as  an
     expression; if the result is non-zero it invokes the  Tcl  interpreter
     on body, then invokes the Tcl interpreter on next,  then  repeats  the
     loop. The command terminates when test evaluates to 0. If  a  continue
     command is invoked within body then  any  remaining  commands  in  the
     current  execution  of  body  are  skipped;  processing  continues  by
     invoking the Tcl interpreter on next, then evaluating test, and so on.
     If a break command is invoked  within  body  or  next,  then  the  for
     command will return immediately. The operation of break  and  continue
     are similar to the corresponding statements in C. For returns an empty
     string. 
     Note: test should  almost  always  be  enclosed  in  braces.  If  not,
     variable substitutions will be made  before  the  for  command  starts
     executing, which means that variable changes made  by  the  loop  body
     will not be considered in the expression. This is likely to result  in
     an infinite loop. If test  is    enclosed    in    braces,    variable
     substitutions are delayed until the expression  is  evaluated  (before
     each loop iteration), so changes in the variables will be visible. For
     an example, try the following  script  with  and  without  the  braces
     around $x<10: for {set x 0} {$x<10} {incr x} { puts "x is $x" }

SEE ALSO
     break, continue, foreach, while

KEYWORDS 
     for, iteration, looping






_________________________________________________________________

NAME
     foreach - Iterate over all elements in one or more lists

SYNOPSIS
	foreach varname list body
	foreach varlist1 list1 ?varlist2 list2 ...? body

_________________________________________________________________

DESCRIPTION 
     The foreach command implements a loop where the loop variable(s)  take
     on values from one or more lists. In the simplest case  there  is  one
     loop variable, varname, and one list, list, that is a list  of  values
     to assign to varname. The body argument is  a  Tcl  script.  For  each
     element of list (in order from first to  last),  foreach  assigns  the
     contents of the element to varname as if the lindex command  had  been
     used to extract the element, then calls the Tcl interpreter to execute
     body. 
     In the general case there can be  more  than  one  value  list  (e.g.,
     list1 and list2), and each value list can be associated with a list of
     loop variables (e.g., varlist1 and varlist2). During each iteration of
     the loop the variables of each varlist are assigned consecutive values
     from the corresponding list. Values in each list  are  used  in  order
     from first to last, and each value is used  exactly  once.  The  total
     number of loop iterations is large enough to use  up  all  the  values
     from all the value lists. If a value  list  does  not  contain  enough
     elements for each of its  loop  variables  in  each  iteration,  empty
     values are used for the missing elements.
     The break and continue statements may be  invoked  inside  body,  with
     the same effect as in  the  for  command.  Foreach  returns  an  empty
     string. 

EXAMPLES 
     The following loop uses i and j as  loop  variables  to  iterate  over
     pairs of elements of a single list. set x {} foreach {i j} {a b c d  e
     f} { lappend x $j $i } # The value of x is "b a d c f e" # There are 3
     iterations of the loop.
     The next loop uses i and j to iterate over two lists in parallel.  set
     x {} foreach i {a b c} j {d e f g} { lappend x $i $j } # The value  of
     x is "a d b e c f {} g" # There are 4 iterations of the loop.
     The two forms are combined in the following example. set x {}  foreach
     i {a b c} {j k} {d e f g} { lappend x $i $j $k } # The value of  x  is
     "a d e b f g c {} {}" # There are 3 iterations of the loop.

SEE ALSO
     for, while, break, continue

KEYWORDS 
     foreach, iteration, list, looping






_________________________________________________________________

NAME
     format - Format a string in the style of sprintf

SYNOPSIS
	format formatString ?arg arg ...?

INTRODUCTION 
     This command generates a formatted string in the same way as the  ANSI
     C sprintf procedure (it uses  sprintf    in    its    implementation).
     FormatString indicates how to format the result,  using  %  conversion
     specifiers as in  sprintf,  and  the  additional  arguments,  if  any,
     provide values to be substituted into the  result.  The  return  value
     from format is the formatted string.


DETAILS ON FORMATTING
     The command operates by scanning formatString from left to right. Each
     character from the format string is  appended  to  the  result  string
     unless it is a percent sign. If the character is a % then  it  is  not
     copied to the result string. Instead, the characters following  the  %
     character are  treated  as  a  conversion  specifier.  The  conversion
     specifier controls the conversion of the  next  successive  arg  to  a
     particular format and the result is appended to the result  string  in
     place of the conversion specifier. If there  are  multiple  conversion
     specifiers in the format string, then each one controls the conversion
     of one additional arg. The format command must be given enough args to
     meet the needs of all of the conversion specifiers in formatString.
     Each conversion specifier may contain up to six  different  parts:  an
     XPG3 position specifier, a set of flags,  a  minimum  field  width,  a
     precision, a length modifier, and a conversion character. Any of these
     fields may be omitted except for the conversion character. The  fields
     that are present must appear in the order given above. The  paragraphs
     below discuss each of these fields in turn.
     If the % is followed by a decimal number and  a  $,  as  in  ``%2$d'',
     then the value to convert  is  not  taken  from  the  next  sequential
     argument. Instead, it is taken from  the  argument  indicated  by  the
     number, where 1 corresponds  to  the  first  arg.  If  the  conversion
     specifier requires multiple arguments because of * characters  in  the
     specifier then  successive  arguments  are  used,  starting  with  the
     argument given by the number. This follows the  XPG3  conventions  for
     positional specifiers. If  there  are  any  positional  specifiers  in
     formatString then all of the specifiers must be positional.
     The second portion of a conversion specifier may contain  any  of  the
     following flag characters, in any order:
          - 
               Specifies that  the    converted    argument    should    be
               left-justified in its   field    (numbers    are    normally
               right-justified with leading spaces if needed).
          + 
               Specifies that a number should  always  be  printed  with  a
               sign, even if positive.
          space 
               Specifies that a space should be added to the  beginning  of
               the number if the first character isn't a sign.
          0 
               Specifies that the number should be padded on the left  with
               zeroes instead of spaces.
          # 
               Requests an alternate output form. For o and  O  conversions
               it guarantees that the first digit is always 0. For x  or  X
               conversions, 0x or 0X (respectively) will be  added  to  the
               beginning of the result unless it  is    zero.    For    all
               floating-point conversions (e, E, f, g, and G) it guarantees
               that the result always has a decimal  point.  For  g  and  G
               conversions it specifies that trailing zeroes should not  be
               removed. 
     The third portion of a conversion  specifier  is  a  number  giving  a
     minimum field width for this conversion. It is typically used to  make
     columns line up  in  tabular  printouts.  If  the  converted  argument
     contains fewer characters than the minimum field width then it will be
     padded so that it is as wide  as  the  minimum  field  width.  Padding
     normally occurs by adding extra spaces on the left  of  the  converted
     argument, but the 0 and - flags may be used to  specify  padding  with
     zeroes on the left or with spaces on the right, respectively.  If  the
     minimum field width is specified as * rather than a number,  then  the
     next argument to the  format  command  determines  the  minimum  field
     width; it must be a numeric string.
     The fourth portion of a conversion specifier  is  a  precision,  which
     consists of a period followed by a  number.  The  number  is  used  in
     different ways for different conversions. For e, E, and f  conversions
     it specifies the number of digits  to  appear  to  the  right  of  the
     decimal point. For g and G conversions it specifies the  total  number
     of digits to appear, including those on  both  sides  of  the  decimal
     point (however, trailing zeroes after the decimal point will still  be
     omitted unless the # flag has    been    specified).    For    integer
     conversions, it specifies a minimum number of digits to print (leading
     zeroes will be added if necessary). For s conversions it specifies the
     maximum number of characters to be printed; if the  string  is  longer
     than this then  the  trailing  characters  will  be  dropped.  If  the
     precision is specified with * rather  than  a  number  then  the  next
     argument to the format command determines the precision; it must be  a
     numeric string.
     The fifth part of a conversion specifier is a length  modifier,  which
     must be h or l. If it is h it specifies that the numeric value  should
     be truncated to a 16-bit  value  before  converting.  This  option  is
     rarely useful. The l modifier is ignored.
     The last thing in a conversion specifier is  an  alphabetic  character
     that determines what kind of  conversion  to  perform.  The  following
     conversion characters are currently supported:
          d 
               Convert integer to signed decimal string.
          u 
               Convert integer to unsigned decimal string.
          i 
               Convert integer to signed decimal string;  the  integer  may
               either be in decimal, in octal (with  a  leading  0)  or  in
               hexadecimal (with a leading 0x).
          o 
               Convert integer to unsigned octal string.
          x or X
               Convert integer to unsigned hexadecimal string, using digits
               ``0123456789abcdef'' for x and ``0123456789ABCDEF'' for X).
          c 
               Convert integer to the Unicode character it represents.
          s 
               No conversion; just insert string.
          f 
               Convert floating-point number to signed  decimal  string  of
               the form xx.yyy, where the number of y's  is  determined  by
               the precision (default: 6). If the precision is  0  then  no
               decimal point is output.
          e or e
               Convert floating-point number to scientific notation in  the
               form x.yyyezz, where the number of y's is determined by the
               precision (default: 6).  If  the  precision  is  0  then  no
               decimal point is output. If the E form is  used  then  E  is
               printed instead of e.
          g or G
               If the exponent is less than -4 or greater than or equal  to
               the precision, then convert floating-point number as for  %e
               or %E. Otherwise convert as for %f. Trailing  zeroes  and  a
               trailing decimal point are omitted.
          % 
               No conversion: just insert %.
     For the numerical conversions the argument being converted must be  an
     integer or floating-point string;  format  converts  the  argument  to
     binary and then  converts  it  back  to  a  string  according  to  the
     conversion specifier.


DIFFERENCES FROM ANSI SPRINTF
     The behavior of the format command is the same as the ANSI  C  sprintf
     procedure except for the following differences:
          [1] 
               %p and %n specifiers are not currently supported.
          [2] 
               For %c conversions the argument must be  a  decimal  string,
               which will then be converted to the corresponding  character
               value. 
          [3] 
               The  l  modifier  is  ignored;  integer  values  are  always
               converted as if there were  no  modifier  present  and  real
               values are always  converted  as  if  the  l  modifier  were
               present (i.e. type double is  used    for    the    internal
               representation). If the h modifier is specified then integer
               values are truncated to short before conversion.

SEE ALSO
     sprintf, string

KEYWORDS 
     conversion specifier, format, sprintf, string, substitution






_________________________________________________________________

NAME
     gets - Read a line from a channel

SYNOPSIS
	gets channelId ?varName?

_________________________________________________________________

DESCRIPTION 
     This command reads the next line from channelId, returns everything in
     the line up to (but not including) the end-of-line  character(s),  and
     discards the end-of-line character(s). If varName is omitted the  line
     is returned as the result of the command. If varName is specified then
     the line is placed in the variable by that name and the  return  value
     is a count of the number of characters returned.
     If end of file occurs while scanning for an end of line,  the  command
     returns whatever input  is  available  up  to  the  end  of  file.  If
     channelId is in nonblocking mode and there is not a full line of input
     available, the command returns an empty string and  does  not  consume
     any input. If varName is specified and an empty string is returned  in
     varName because of end-of-file or  because  of  insufficient  data  in
     nonblocking mode, then the return count is -1. Note that if varName is
     not specified then the end-of-file  and  no-full-line-available  cases
     can produce the same results as if there were an input line consisting
     only of the end-of-line character(s). The eof  and  fblocked  commands
     can be used to distinguish these three cases.


SEE ALSO
     file, eof, fblocked

KEYWORDS 
     blocking, channel, end of file, end of line, line, nonblocking, read






_________________________________________________________________

NAME
     glob - Return names of files that match patterns

SYNOPSIS
	glob ?switches? pattern ?pattern ...?

_________________________________________________________________

DESCRIPTION 
     This command performs file name ``globbing'' in a fashion  similar  to
     the csh shell. It returns a list of the files whose names match any of
     the pattern arguments.
     If the initial arguments to glob start with - then  they  are  treated
     as switches. The following switches are currently supported:
          -directory directory
               Search for files which match the given patterns starting  in
               the given directory. This allows  searching  of  directories
               whose name contains glob-sensitive  characters  without  the
               need to quote such characters explicitly.  This  option  may
               not be used in conjunction with -path.
          -join 
               The remaining pattern arguments  are  treated  as  a  single
               pattern obtained by joining  the  arguments  with  directory
               separators. 
          -nocomplain 
               Allows an empty list to be returned without  error;  without
               this switch an error is returned if the result list would be
               empty. 
          -path pathPrefix
               Search for files with the given pathPrefix where the rest of
               the name matches the given patterns. This  allows  searching
               for files with names similar to a given file even  when  the
               names contain glob-sensitive characters. This option may not
               be used in conjunction with -directory.
          -types typeList
               Only list files or directories which match  typeList,  where
               the items in the list have two forms. The first form is like
               the -type option of the Unix find command: b (block  special
               file), c (character special file), d (directory),  f  (plain
               file), l (symbolic link), p (named  pipe),  or  s  (socket),
               where multiple types may be specified in the list. Glob will
               return all files which match  at  least  one  of  the  types
               given. 
               The second form specifies types where all  the  types  given
               must match. These are r,  w,  x  as  file  permissions,  and
               readonly, hidden as special permission   cases.    On    the
               Macintosh, MacOS types  and  creators  are  also  supported,
               where any item which is four characters long is  assumed  to
               be a MacOS type (e.g. TEXT). Items which  are  of  the  form
               {macintosh type XXXX} or {macintosh creator XXXX} will match
               types  or  creators  respectively.  Unrecognised  types,  or
               specifications of multiple MacOS types/creators will  signal
               an error.
               The two forms may be mixed, so -types {d f r  w}  will  find
               all regular files OR directories that  have  both  read  AND
               write permissions. The following are equivalent: glob  -type
               d * glob */ except that the first case  doesn't  return  the
               trailing ``/'' and is more platform independent.
          -- 
               Marks the end of switches. The argument following  this  one
               will be treated as a pattern even if it starts with a -.
     The pattern  arguments  may  contain  any  of  the  following  special
     characters: 
          ? 
               Matches any single character.
          * 
               Matches any sequence of zero or more characters.
          [chars] 
               Matches any single character in chars. If chars  contains  a
               sequence of the form a-b then any character between a and  b
               (inclusive) will match.
          \x 
               Matches the character x.
          {a,b,...} 
               Matches any of the strings a, b, etc.
     As with csh, a ``.'' at the beginning of a file's name or  just  after
     a ``/'' must  be  matched  explicitly  or  with  a  {}  construct.  In
     addition, all ``/'' characters must be matched explicitly.
     If the first character in a pattern is ``~'' then  it  refers  to  the
     home directory for the user whose name follows the ``~''. If the ``~''
     is followed immediately by ``/'' then the   value    of    the    HOME
     environment variable is used.
     The glob command differs from csh globbing  in  two  ways.  First,  it
     does not sort its result list (use the lsort command if you  want  the
     list sorted). Second, glob  only  returns  the  names  of  files  that
     actually exist; in csh no check for existence is made unless a pattern
     contains a ?, *, or [] construct.


PORTABILITY ISSUES
     Unlike other Tcl commands that will accept  both  network  and  native
     style names (see the filename manual entry for details on  how  native
     and network names are specified), the glob command only accepts native
     names. 
          Windows 
               For Windows UNC names, the    servername    and    sharename
               components  of  the  path  may  not  contain  ?,  *,  or  []
               constructs. On  Windows  NT,  if  pattern  is  of  the  form
               ``~username@domain'' it refers to the home directory of  the
               user whose account information resides on the  specified  NT
               domain server. Otherwise, user  account    information    is
               obtained from the local computer. On Windows 95 and 98, glob
               accepts patterns like    ``.../''    and    ``..../''    for
               successively higher up parent directories.
          Macintosh 
               When using the options, -dir, -join or -path,  glob  assumes
               the directory  separator  for  the  entire  pattern  is  the
               standard ``:''. When not using these options, glob  examines
               each pattern argument and  uses  ``/''  unless  the  pattern
               contains a ``:''.

SEE ALSO
     file 

KEYWORDS 
     exist, file, glob, pattern






_________________________________________________________________

NAME
     global - Access global variables

SYNOPSIS
	global varname ?varname ...?

_________________________________________________________________

DESCRIPTION 
     This command is ignored unless a Tcl procedure is  being  interpreted.
     If so then it declares the given  varname's  to  be  global  variables
     rather than local ones. Global variables are variables in  the  global
     namespace. For the duration of the current procedure (and  only  while
     executing in the current procedure),  any  reference  to  any  of  the
     varnames will refer to the global variable by the same name.


SEE ALSO
     namespace, variable

KEYWORDS 
     global, namespace, procedure, variable






_________________________________________________________________

NAME
     history - Manipulate the history list

SYNOPSIS
	history ?option? ?arg arg ...?

_________________________________________________________________

DESCRIPTION 
     The history command performs one  of  several  operations  related  to
     recently-executed commands recorded in a history list. Each  of  these
     recorded commands is referred to as an ``event''. When  specifying  an
     event to the history command, the following forms may be used:
          [1] 
               A number: if positive, it refers  to  the  event  with  that
               number (all events are  numbered  starting  at  1).  If  the
               number is negative, it selects  an  event  relative  to  the
               current event (-1 refers to the previous event,  -2  to  the
               one before that, and so on). Event 0 refers to  the  current
               event. 
          [2] 
               A string: selects the most recent  event  that  matches  the
               string. An event is considered to match the string either if
               the string is the same as the first characters of the event,
               or if the string matches the  event  in  the  sense  of  the
               string match command.
     The history command can take any of the following forms:
          history 
               Same as history info, described below.
          history add command ?exec?
               Adds the command argument to  the  history  list  as  a  new
               event. If  exec  is  specified  (or  abbreviated)  then  the
               command is also executed and its result is returned. If exec
               isn't specified then an empty string is returned as result.
          history change newValue ?event?
               Replaces the value recorded  for  an  event  with  newValue.
               Event specifies the event to replace, and  defaults  to  the
               current event (not event -1). This command is  intended  for
               use in commands that implement new    forms    of    history
               substitution and wish to replace the  current  event  (which
               invokes the substitution) with the command  created  through
               substitution. The return value is an empty string.
          history clear
               Erase the history list. The current keep limit is  retained.
               The history event numbers are reset.
          history event ?event?
               Returns the  value  of  the  event  given  by  event.  Event
               defaults to -1.
          history info ?count?
               Returns a formatted string (intended  for  humans  to  read)
               giving the event number and contents for each of the  events
               in the history list except the current event.  If  count  is
               specified  then  only  the  most  recent  count  events  are
               returned. 
          history keep ?count?
               This command may be used to change the size of  the  history
               list to count events. Initially, 20 events are  retained  in
               the history list. If count is  not  specified,  the  current
               keep limit is returned.
          history nextid
               Returns the number of the next event to be recorded  in  the
               history list. It is useful  for  things  like  printing  the
               event number in command-line prompts.
          history redo ?event?
               Re-executes the command indicated by event  and  return  its
               result. Event  defaults  to  -1.  This  command  results  in
               history revision: see below for details.
HISTORY REVISION
     Pre-8.0 Tcl had a complex  history  revision  mechanism.  The  current
     mechanism is more limited, and the old history  operations  substitute
     and words have been removed. (As a consolation,  the  clear  operation
     was added.)
     The history option redo results in much simpler ``history  revision''.
     When this option is invoked then the most recent event is modified  to
     eliminate the history command and replace it with the  result  of  the
     history command. If you  want  to  redo  an  event  without  modifying
     history, then use the event operation to retrieve some event, and  the
     add operation to add it to history and execute it.


KEYWORDS 
     event, history, record






_________________________________________________________________

NAME
     Http - Client-side implementation of the HTTP/1.0 protocol.

SYNOPSIS
	package require http ?2.3?
	::http::config ?options?
	::http::geturl url ?options?
	::http::formatQuery list
	::http::reset token
	::http::wait token
	::http::status token
	::http::size token
	::http::code token
	::http::ncode token
	::http::data token
	::http::error token
	::http::cleanup token
	::http::register proto port command
	::http::unregister proto

_________________________________________________________________

DESCRIPTION 
     The http package provides the client side of  the  HTTP/1.0  protocol.
     The package implements the GET, POST, and HEAD operations of HTTP/1.0.
     It allows configuration of a proxy host to get through firewalls.  The
     package is compatible with the Safesock security policy, so it can  be
     used by untrusted applets to do URL fetching from a restricted set  of
     hosts.  This  package  can  be  extened  to  support  additional  HTTP
     transport protocols, such as  HTTPS,  by  providing  a  custom  socket
     command, via http::register.
     The ::http::geturl procedure does  a  HTTP  transaction.  Its  options
     determine whether a GET, POST, or HEAD transaction is  performed.  The
     return value of ::http::geturl is a token  for  the  transaction.  The
     value is also the name of  an  array  in  the  ::http  namespace  that
     contains state information about the transaction. The elements of this
     array are described in the STATE ARRAY section.
     If the -command option is specified, then the HTTP operation  is  done
     in the background. ::http::geturl returns immediately after generating
     the HTTP request and the callback  is  invoked  when  the  transaction
     completes. For this to work, the Tcl event loop must be active. In  Tk
     applications this is  always  true.  For  pure-Tcl  applications,  the
     caller can use ::http::wait after calling ::http::geturl to start  the
     event loop.

COMMANDS 
          ::http::config ?options?
               The ::http::config command is used to set and query the name
               of the proxy server and port, and the User-Agent  name  used
               in the HTTP requests. If no options are specified, then  the
               current configuration is returned. If a single  argument  is
               specified, then it should be  one  of  the  flags  described
               below. In this case the current value  of  that  setting  is
               returned. Otherwise, the options should be a  set  of  flags
               and values that define the configuration:
                    -accept mimetypes
                         The Accept header of the request. The  default  is
                         */*, which means that all types of  documents  are
                         accepted. Otherwise you can   supply    a    comma
                         separated list of mime type patterns that you  are
                         willing to receive. For    example,    "image/gif,
                         image/jpeg, text/*".
                    -proxyhost hostname
                         The name of the proxy host, if any. If this  value
                         is the empty string, the  URL  host  is  contacted
                         directly. 
                    -proxyport number
                         The proxy port number.
                    -proxyfilter command
                         The command is a  callback  that  is  made  during
                         ::http::geturl to determine if a proxy is required
                         for a given host. One argument, a  host  name,  is
                         added to command when it is invoked. If a proxy is
                         required, the callback should return a two element
                         list containing the proxy server and  proxy  port.
                         Otherwise the filter should return an empty  list.
                         The default  filter  returns  the  values  of  the
                         -proxyhost and -proxyport  settings  if  they  are
                         non-empty. 
                    -useragent string
                         The value of the User-Agent  header  in  the  HTTP
                         request. The default is "Tcl http  client  package
                         2.2." 
          ::http::geturl url ?options?
               The ::http::geturl command is  the  main  procedure  in  the
               package. The -query option causes a POST operation  and  the
               -validate option causes a HEAD operation; otherwise,  a  GET
               operation is performed. The ::http::geturl command returns a
               token value that can be used to get  information  about  the
               transaction. See the STATE  ARRAY  and  ERRORS  section  for
               details. The ::http::geturl command   blocks    until    the
               operation completes, unless the -command option specifies  a
               callback that is invoked  when    the    HTTP    transaction
               completes. ::http::geturl takes several options:
                    -blocksize size
                         The blocksize used when reading the URL.  At  most
                         size bytes are read at once. After each  block,  a
                         call to the -progress callback is  made  (if  that
                         option is specified).
                    -channel name
                         Copy the URL contents to channel name  instead  of
                         saving it in state(body).
                    -command callback
                         Invoke callback after   the    HTTP    transaction
                         completes. This option  causes  ::http::geturl  to
                         return immediately.  The    callback    gets    an
                         additional argument that  is  the  token  returned
                         from ::http::geturl. This token is the name of  an
                         array that is described in   the    STATE    ARRAY
                         section. Here is a template for the callback: proc
                         httpCallback {token} { upvar  #0  $token  state  #
                         Access state as a Tcl array }
                    -handler callback
                         Invoke callback whenever HTTP data  is  available;
                         if present, nothing else will  be  done  with  the
                         HTTP data.  This  procedure  gets  two  additional
                         arguments: the socket for the HTTP  data  and  the
                         token returned from ::http::geturl. The  token  is
                         the name of a global array that  is  described  in
                         the STATE ARRAY section. The procedure is expected
                         to return  the  number  of  bytes  read  from  the
                         socket. Here is a template for the callback:  proc
                         httpHandlerCallback  {socket  token}  {  upvar  #0
                         $token state # Access socket, and state as  a  Tcl
                         array ... (example: set   data    [read    $socket
                         1000];set nbytes [string length $data]) ... return
                         nbytes }
                    -headers keyvaluelist
                         This option is used to add extra  headers  to  the
                         HTTP request. The keyvaluelist argument must be  a
                         list with an even number    of    elements    that
                         alternate between keys and values. The keys become
                         header field names. Newlines are stripped from the
                         values so the  header  cannot  be  corrupted.  For
                         example, if keyvaluelist is Pragma  no-cache  then
                         the following  header  is  included  in  the  HTTP
                         request: Pragma: no-cache
                    -progress callback
                         The callback is made after each transfer  of  data
                         from the URL. The callback gets  three  additional
                         arguments:  the  token  from  ::http::geturl,  the
                         expected total  size  of  the  contents  from  the
                         Content-Length meta-data, and the  current  number
                         of bytes transferred so far.  The  expected  total
                         size may be unknown, in which case zero is  passed
                         to the  callback.  Here  is  a  template  for  the
                         progress callback: proc httpProgress {token  total
                         current} { upvar #0 $token state }
                    -query query
                         This flag  causes  ::http::geturl  to  do  a  POST
                         request that passes the query to the  server.  The
                         query must be a  x-url-encoding  formatted  query.
                         The ::http::formatQuery procedure can be  used  to
                         do the formatting.
                    -queryblocksize size
                         The blocksize used when posting query data to  the
                         URL. At most size bytes are written at once. After
                         each block, a call to the -queryprogress  callback
                         is made (if that option is specified).
                    -querychannel channelID
                         This flag  causes  ::http::geturl  to  do  a  POST
                         request that passes the    data    contained    in
                         channelID to the server.  The  data  contained  in
                         channelID must be a x-url-encoding formatted query
                         unless the  -type  option  below  is  used.  If  a
                         Content-Length header is  not  specified  via  the
                         -headers options, ::http::geturl    attempts    to
                         determine the size of the post data  in  order  to
                         create that header. If it is unable  to  determine
                         the size, it returns an error.
                    -queryprogress callback
                         The callback is made after each transfer  of  data
                         to the URL (i.e. POST) and acts exactly  like  the
                         -progress  option  (the  callback  format  is  the
                         same). 
                    -timeout milliseconds
                         If milliseconds is non-zero,  then  ::http::geturl
                         sets up a timeout to  occur  after  the  specified
                         number of milliseconds. A  timeout  results  in  a
                         call to ::http::reset and    to    the    -command
                         callback, if specified. The  return    value    of
                         ::http::status is  timeout  after  a  timeout  has
                         occurred. 
                    -type mime-type
                         Use mime-type as the Content-Type  value,  instead
                         of the                default                value
                         (application/x-www-form-urlencoded) during a  POST
                         operation. 
                    -validate boolean
                         If boolean is non-zero, then  ::http::geturl  does
                         an HTTP HEAD request. This  request  returns  meta
                         information about the URL, but  the  contents  are
                         not returned. The meta information is available in
                         the state(meta) variable  after  the  transaction.
                         See the STATE ARRAY section for details.
          ::http::formatQuery key value ?key value ...?
               This procedure does x-url-encoding of query data.  It  takes
               an even number of arguments that are the keys and values  of
               the query. It encodes the keys and values, and generates one
               string that has the proper & and = separators. The result is
               suitable for the -query value passed to ::http::geturl.
          ::http::reset token ?why?
               This command  resets  the  HTTP  transaction  identified  by
               token, if any. This sets the  state(status)  value  to  why,
               which defaults to  reset,  and  then  calls  the  registered
               -command callback.
          ::http::wait token
               This is a convenience procedure that blocks  and  waits  for
               the transaction to complete. This only works in trusted code
               because it uses vwait. Also, it's not useful  for  the  case
               where ::http::geturl is called without the  -command  option
               because in this case the ::http::geturl call doesn't  return
               until the HTTP transaction is  complete,  and  thus  there's
               nothing to wait for.
          ::http::data token
               This is  a  convenience  procedure  that  returns  the  body
               element (i.e., the URL data) of the state array.
          ::http::error token
               This is a  convenience  procedure  that  returns  the  error
               element of the state array.
          ::http::status token
               This is a convenience  procedure  that  returns  the  status
               element of the state array.
          ::http::code token
               This is  a  convenience  procedure  that  returns  the  http
               element of the state array.
          ::http::ncode token
               This is  a  convenience  procedure  that  returns  just  the
               numeric return code (200, 404, etc.) from the  http  element
               of the state array.
          ::http::size token
               This is a convenience procedure that returns the currentsize
               element of the state array, which represents the  number  of
               bytes received from the URL in the ::http::geturl call.
          ::http::cleanup token
               This procedure cleans  up  the  state  associated  with  the
               connection identified by token. After   this    call,    the
               procedures like ::http::data cannot  be    used    to    get
               information about the operation. It is strongly  recommended
               that you call this function after you're done with  a  given
               HTTP request. Not doing so will result in memory  not  being
               freed, and if your app calls  ::http::geturl  enough  times,
               the memory leak could cause a performance hit...or worse.
          ::http::register proto port command
               This procedure allows one to provide custom  HTTP  transport
               types such as HTTPS, by registering a  prefix,  the  default
               port, and the command to execute to create the Tcl  channel.
               E.g.: package require http package require tls

http::register https 443 ::tls::socket

set token [http::geturl https://my.secure.site/]
          ::http::unregister proto
               This procedure  unregisters  a  protocol  handler  that  was
               previously registered via http::register.

ERRORS 
     The http::geturl procedure will raise errors in the  following  cases:
     invalid command line options, an invalid URL, a URL on a  non-existent
     host, or a URL at a bad port on an existing host.  These  errors  mean
     that it cannot even start the network transaction. It will also  raise
     an error if it gets an I/O error while writing out  the  HTTP  request
     header. For synchronous ::http::geturl calls (where  -command  is  not
     specified), it will raise an error if  it  gets  an  I/O  error  while
     reading the HTTP reply headers or data. Because ::http::geturl doesn't
     return a token in these cases, it does all the  required  cleanup  and
     there's no issue of your app having to call ::http::cleanup.
     For asynchronous ::http::geturl calls, all of    the    above    error
     situations apply, except that if there's any error while  reading  the
     HTTP reply headers or data, no exception is thrown.  This  is  because
     after writing the HTTP headers, ::http::geturl returns, and  the  rest
     of the HTTP transaction occurs in the background. The command callback
     can check if any error occurred during    the    read    by    calling
     ::http::status  to  check  the  status  and  if  it's  error,  calling
     ::http::error to get the error message.
     Alternatively, if the main program  flow  reaches  a  point  where  it
     needs to know the result of the asynchronous HTTP request, it can call
     ::http::wait and then check status and error,  just  as  the  callback
     does. 
     In any case, you must still call http::cleanup  to  delete  the  state
     array when you're done.
     There are other possible results of the  HTTP  transaction  determined
     by examining the status from http::status. These are described below.
          ok 
               If the HTTP transaction completes entirely, then status will
               be ok. However, you should still check the http::code  value
               to get the HTTP status. The http::ncode  procedure  provides
               just the numeric error (e.g., 200, 404  or  500)  while  the
               http::code procedure returns a value like "HTTP 404 File not
               found". 
          eof 
               If the server closes the socket without  replying,  then  no
               error is raised, but the status of the transaction  will  be
               eof. 
          error 
               The error message will also be stored in  the  error  status
               array element, accessible via ::http::error.
     Another error possibility is that http::geturl is unable to write  all
     the post query data to the  server  before  the  server  responds  and
     closes the socket. The error message is saved in the posterror  status
     array element and then http::geturl  attempts    to    complete    the
     transaction. If it can read the server's response it will end up  with
     an ok status, otherwise it will have an eof status.


STATE ARRAY
     The ::http::geturl procedure returns a token that can be used  to  get
     to the state of the HTTP transaction in the form of a Tcl  array.  Use
     this construct to create  an  easy-to-use  array  variable:  upvar  #0
     $token state Once the data  associated  with  the  url  is  no  longer
     needed, the state array should  be  unset  to  free  up  storage.  The
     http::cleanup procedure is provided for that  purpose.  The  following
     elements of the array are supported:
          body 
               The contents of the URL. This will be empty if the  -channel
               option has been specified. This value  is  returned  by  the
               ::http::data command.
          currentsize 
               The current number of bytes fetched from the URL. This value
               is returned by the ::http::size command.
          error 
               If defined, this is the error  string  seen  when  the  HTTP
               transaction was aborted.
          http 
               The HTTP  status  reply  from  the  server.  This  value  is
               returned by the ::http::code command.  The  format  of  this
               value is: HTTP/1.0 code string The  code  is  a  three-digit
               number defined in the HTTP standard. A code of  200  is  OK.
               Codes beginning with 4 or 5 indicate errors. Codes beginning
               with 3 are redirection errors. In  this  case  the  Location
               meta-data specifies a new URL that  contains  the  requested
               information. 
          meta 
               The HTTP protocol returns meta-data that describes  the  URL
               contents. The meta element of the state array is a  list  of
               the keys and values of the meta-data. This is  in  a  format
               useful for initializing an  array  that  just  contains  the
               meta-data: array set meta $state(meta) Some of the meta-data
               keys are listed below, but the HTTP standard  defines  more,
               and servers are free to add their own.
                    Content-Type 
                         The type of the  URL  contents.  Examples  include
                         text/html, image/gif,  application/postscript  and
                         application/x-tcl. 
                    Content-Length 
                         The advertised size of the  contents.  The  actual
                         size obtained by ::http::geturl  is  available  as
                         state(size). 
                    Location 
                         An alternate URL that contains the requested data.
                          
          posterror 
               The error, if any, that  occurred  while  writing  the  post
               query data to the server.
          status 
               Either ok, for successful completion, reset for  user-reset,
               timeout if a timeout occurred before the  transaction  could
               complete, or  error  for  an  error  condition.  During  the
               transaction this value is the empty string.
          totalsize 
               A copy of the Content-Length meta-data value.
          type 
               A copy of the Content-Type meta-data value.
          url 
               The requested URL.
                
      
EXAMPLE 
     # Copy a URL to a file and print meta-data  proc  ::http::copy  {  url
     file {chunk 4096} } { set out [open $file w] set  token  [geturl  $url
     -channel $out -progress ::http::Progress \  -blocksize  $chunk]  close
     $out # This ends the line started by  http::Progress  puts  stderr  ""
     upvar #0 $token state set max 0 foreach {name value} $state(meta) { if
     {[string length $name] > $max} { set max [string length  $name]  }  if
     {[regexp -nocase ^location$ $name]} {  #  Handle  URL  redirects  puts
     stderr "Location:$value"  return  [copy  [string  trim  $value]  $file
     $chunk] } } incr max foreach {name value} $state(meta) { puts  [format
     "%-*s %s" $max $name: $value] }

    return $token
}
proc ::http::Progress {args} {
    puts -nonewline stderr . ; flush stderr
}

SEE ALSO
     safe, socket, safesock

KEYWORDS 
     security policy, socket






_________________________________________________________________

NAME
     if - Execute scripts conditionally

SYNOPSIS
	if expr1 ?then? body1 elseif expr2 ?then? body2 elseif ... ?else? ?bodyN?

_________________________________________________________________

DESCRIPTION 
     The if command evaluates expr1 as an expression (in the same way  that
     expr evaluates its argument). The value of the expression  must  be  a
     boolean (a numeric value, where 0 is false and anything is true, or  a
     string value such as true or yes for true and false or no for  false);
     if it is true then  body1  is  executed  by  passing  it  to  the  Tcl
     interpreter. Otherwise expr2 is evaluated as an expression and  if  it
     is true then body2 is executed, and so on. If none of the  expressions
     evaluates to true then bodyN is executed. The then and else  arguments
     are optional ``noise words'' to make the command easier to read. There
     may be any number of elseif clauses, including zero. BodyN may also be
     omitted as long as else is omitted too.  The  return  value  from  the
     command is the result of the body script  that  was  executed,  or  an
     empty string if none of the expressions was non-zero and there was  no
     bodyN. 


SEE ALSO
     expr, for, foreach

KEYWORDS 
     boolean, conditional, else, false, if, true






_________________________________________________________________

NAME
     incr - Increment the value of a variable

SYNOPSIS
	incr varName ?increment?

_________________________________________________________________

DESCRIPTION 
     Increments the value stored in the variable whose name is varName. The
     value of the variable must be an integer.  If  increment  is  supplied
     then its value (which must be an integer) is added  to  the  value  of
     variable varName; otherwise 1 is added to varName. The  new  value  is
     stored as a decimal string in variable varName and  also  returned  as
     result. 


SEE ALSO
     expr 

KEYWORDS 
     add, increment, variable, value






_________________________________________________________________

NAME
     info - Return information about the state of the Tcl interpreter

SYNOPSIS
	info option ?arg arg ...?

_________________________________________________________________

DESCRIPTION 
     This command provides information about various internals of  the  Tcl
     interpreter. The legal option's (which may be abbreviated) are:
          info args procname
               Returns a list containing the  names  of  the  arguments  to
               procedure procname, in order. Procname must be the name of a
               Tcl command procedure.
          info body procname
               Returns the body of procedure procname. Procname must be the
               name of a Tcl command procedure.
          info cmdcount
               Returns a count of the total number of  commands  that  have
               been invoked in this interpreter.
          info commands ?pattern?
               If pattern isn't specified, returns a list of names  of  all
               the Tcl commands in the current  namespace,  including  both
               the built-in commands written in  C    and    the    command
               procedures defined using the proc  command.  If  pattern  is
               specified, only those names matching pattern  are  returned.
               Matching is determined using the same rules  as  for  string
               match. pattern can be a  qualified  name  like  Foo::print*.
               That is, it may  specify  a  particular  namespace  using  a
               sequence of namespace names separated by ::s, and  may  have
               pattern matching special characters at the end to specify  a
               set of commands in that namespace. If pattern is a qualified
               name, the resulting list  of  command  names  has  each  one
               qualified with the name of the specified namespace.
          info complete command
               Returns 1 if command is a complete Tcl command in the  sense
               of having no unclosed  quotes,  braces,  brackets  or  array
               element names, If the command doesn't appear to be  complete
               then 0 is  returned.  This  command  is  typically  used  in
               line-oriented input environments to allow users to  type  in
               commands that span multiple  lines;  if  the  command  isn't
               complete, the script can  delay    evaluating    it    until
               additional lines have been typed to complete the command.
          info default procname arg varname
               Procname must be the name of a Tcl command procedure and arg
               must be the name of an argument to that  procedure.  If  arg
               doesn't have a default value then  the  command  returns  0.
               Otherwise it returns 1 and places the default value  of  arg
               into variable varname.
          info exists varName
               Returns 1 if  the  variable  named  varName  exists  in  the
               current context (either as a global or local  variable)  and
               has been defined by being given  a    value,    returns    0
               otherwise. 
          info globals ?pattern?
               If pattern isn't specified, returns a list of all the  names
               of currently-defined global variables. Global variables  are
               variables in the global namespace. If pattern is  specified,
               only those names matching pattern are returned. Matching  is
               determined using the same rules as for string match.
          info hostname
               Returns the name of the computer on which this invocation is
               being executed.
          info level ?number?
               If number is not specified, this command  returns  a  number
               giving the stack level of the invoking procedure,  or  0  if
               the command is invoked at top-level. If number is specified,
               then the result  is  a  list  consisting  of  the  name  and
               arguments for the procedure call  at  level  number  on  the
               stack. If number is positive then it  selects  a  particular
               stack level (1 refers to the top-most active procedure, 2 to
               the procedure it called, and so on); otherwise  it  gives  a
               level relative to the current level (0 refers to the current
               procedure, -1 to its caller, and so  on).  See  the  uplevel
               command for more information on what stack levels mean.
          info library
               Returns the name of the library directory in which  standard
               Tcl scripts are stored. This is actually the  value  of  the
               tcl_library variable and may  be    changed    by    setting
               tcl_library. See the tclvars  manual    entry    for    more
               information. 
          info loaded ?interp?
               Returns a list describing all of the packages that have been
               loaded into interp with the load command. Each list  element
               is a sub-list with two elements consisting of  the  name  of
               the file from which the package was loaded and the  name  of
               the package. For statically-loaded packages  the  file  name
               will be an empty string. If  interp    is    omitted    then
               information is returned  for  all  packages  loaded  in  any
               interpreter in the process.  To  get  a  list  of  just  the
               packages in the current interpreter, specify an empty string
               for the interp argument.
          info locals ?pattern?
               If pattern isn't specified, returns a list of all the  names
               of currently-defined local variables, including arguments to
               the current procedure, if any. Variables  defined  with  the
               global and upvar commands will not be returned.  If  pattern
               is specified, only those names    matching    pattern    are
               returned. Matching is determined using the same rules as for
               string match.
          info nameofexecutable
               Returns the full path name of the binary file from which the
               application was invoked. If Tcl was unable to  identify  the
               file, then an empty string is returned.
          info patchlevel
               Returns the value of the global variable tcl_patchLevel; see
               the tclvars manual entry for more information.
          info procs ?pattern?
               If pattern isn't specified, returns a list of all the  names
               of Tcl command  procedures  in  the  current  namespace.  If
               pattern is specified, only  those  procedure  names  in  the
               current namespace matching pattern are returned. Matching is
               determined using the same rules as for string match.
          info script ?filename?
               If a Tcl script file  is  currently  being  evaluated  (i.e.
               there is a call to Tcl_EvalFile active or there is an active
               invocation of the source command), then this command returns
               the name of the innermost file being processed. If  filename
               is specified, then the return value of this command will  be
               modified for the duration of the active invocation to return
               that name. This is useful    in    virtual    file    system
               applications. Otherwise the command returns an empty string.
                
          info sharedlibextension
               Returns the extension used on this platform for the names of
               files containing shared libraries (for  example,  .so  under
               Solaris). If  shared  libraries  aren't  supported  on  this
               platform then an empty string is returned.
          info tclversion
               Returns the value of the global  variable  tcl_version;  see
               the tclvars manual entry for more information.
          info vars ?pattern?
               If pattern isn't specified, returns a list of all the  names
               of currently-visible variables.  This  includes  locals  and
               currently-visible globals. If  pattern  is  specified,  only
               those names  matching  pattern  are  returned.  Matching  is
               determined using the same rules as for string match. pattern
               can be a qualified name like Foo::option*. That is,  it  may
               specify a particular namespace using a sequence of namespace
               names separated  by  ::s,  and  may  have  pattern  matching
               special characters at the end to specify a set of  variables
               in that namespace. If  pattern  is  a  qualified  name,  the
               resulting list of variable names has each matching namespace
               variable qualified with the name of its namespace.

SEE ALSO
     global, proc

KEYWORDS 
     command, information, interpreter,  level,    namespace,    procedure,
     variable 







_________________________________________________________________

NAME
     interp - Create and manipulate Tcl interpreters

SYNOPSIS
	interp option ?arg arg ...?

_________________________________________________________________

DESCRIPTION 
     This command  makes  it  possible  to  create  one  or  more  new  Tcl
     interpreters that co-exist with the creating interpreter in  the  same
     application. The creating interpreter is called the master and the new
     interpreter is called a slave. A  master  can  create  any  number  of
     slaves, and each slave can itself create additional slaves  for  which
     it is master, resulting in a hierarchy of interpreters.
     Each interpreter is independent from the others: it has its  own  name
     space  for  commands,  procedures,  and  global  variables.  A  master
     interpreter may create connections between its slaves and itself using
     a mechanism called an  alias.  An  alias  is  a  command  in  a  slave
     interpreter which, when invoked, causes a command to be invoked in its
     master interpreter or in another slave  interpreter.  The  only  other
     connections between interpreters  are  through  environment  variables
     (the env variable), which are normally shared among  all  interpreters
     in the application. Note that the name space for files  (such  as  the
     names returned by the  open  command)  is  no  longer  shared  between
     interpreters. Explicit commands are provided to  share  files  and  to
     transfer references to open files from one interpreter to another.
     The interp command also provides  support  for  safe  interpreters.  A
     safe  interpreter  is  a  slave  whose  functions  have  been  greatly
     restricted, so that it is safe to execute  untrusted  scripts  without
     fear of them damaging other interpreters    or    the    application's
     environment.  For  example,  all  IO  channel  creation  commands  and
     subprocess creation commands are    made    inaccessible    to    safe
     interpreters. See SAFE INTERPRETERS below for more information on what
     features are present in  a    safe    interpreter.    The    dangerous
     functionality is not removed from the safe interpreter; instead, it is
     hidden, so that only trusted interpreters can obtain access to it. For
     a detailed explanation of hidden commands, see HIDDEN COMMANDS, below.
     The alias mechanism can be used for protected communication (analogous
     to a kernel call) between a slave  interpreter  and  its  master.  See
     ALIAS INVOCATION, below, for more details on how the  alias  mechanism
     works. 
     A qualified interpreter name  is  a  proper  Tcl  lists  containing  a
     subset of its ancestors in the interpreter  hierarchy,  terminated  by
     the string naming the interpreter in its immediate master. Interpreter
     names are relative to the interpreter in  which  they  are  used.  For
     example, if a is a slave of the current interpreter and it has a slave
     a1, which in turn has a slave a11, the qualified name of a11 in  a  is
     the list a1 a11.
     The interp command, described  below,  accepts  qualified  interpreter
     names as arguments; the interpreter in  which  the  command  is  being
     evaluated can always be referred to as {} (the empty list or  string).
     Note that it is impossible to refer to a master (ancestor) interpreter
     by name in a slave interpreter except through aliases. Also, there  is
     no global name by which one can refer to the first interpreter created
     in an application. Both restrictions are motivated by safety concerns.
      


THE INTERP COMMAND
     The interp command is used to create,  delete,  and  manipulate  slave
     interpreters, and to share or transfer channels between  interpreters.
     It can have any of several forms, depending on the option argument:
          interp alias srcPath srcCmd
               Returns a Tcl list whose elements are the targetCmd and args
               associated with the alias named srcCmd (all of these are the
               values specified when the alias was created; it is  possible
               that the actual source command in  the  slave  is  different
               from srcCmd if it was renamed).
          interp alias srcPath srcCmd {}
               Deletes the  alias  for  srcCmd  in  the  slave  interpreter
               identified by srcPath. srcCmd refers to the name under which
               the alias was  created;  if  the  source  command  has  been
               renamed, the renamed command will be deleted.
          interp alias srcPath srcCmd targetPath targetCmd ?arg arg ...?
               This command creates an alias between one slave and  another
               (see the alias slave  command  below  for  creating  aliases
               between a slave and its master). In this command, either  of
               the slave interpreters may be anywhere in the  hierarchy  of
               interpreters under the  interpreter  invoking  the  command.
               SrcPath and srcCmd identify the source of the alias. SrcPath
               is a Tcl list whose    elements    select    a    particular
               interpreter. For example, ``a b'' identifies an  interpreter
               b, which is a slave of interpreter a, which is  a  slave  of
               the  invoking  interpreter.  An  empty  list  specifies  the
               interpreter invoking the command. srcCmd gives the name of a
               new command, which will be    created    in    the    source
               interpreter.  TargetPath  and  targetCmd  specify  a  target
               interpreter and command, and  the  arg  arguments,  if  any,
               specify additional arguments to    targetCmd    which    are
               prepended to any arguments specified in  the  invocation  of
               srcCmd. TargetCmd may be undefined at the time of this call,
               or it may already exist; it is not created by this  command.
               The alias arranges  for  the  given  target  command  to  be
               invoked in the target interpreter whenever the given  source
               command is invoked in  the  source  interpreter.  See  ALIAS
               INVOCATION below for more details.
          interp aliases ?path?
               This command returns a Tcl list of  the  names  of  all  the
               source commands  for  aliases  defined  in  the  interpreter
               identified by path.
          interp create ?-safe? ?--? ?path?
               Creates a slave interpreter identified by  path  and  a  new
               command, called a slave  command.  The  name  of  the  slave
               command is  the  last  component  of  path.  The  new  slave
               interpreter  and  the  slave  command  are  created  in  the
               interpreter identified by the path obtained by removing  the
               last component from path. For example, if path is a b c then
               a new slave  interpreter  and  slave  command  named  c  are
               created in the interpreter identified by the path a  b.  The
               slave command may be used to manipulate the new  interpreter
               as described below. If path is omitted, Tcl creates a unique
               name of the form interpx, where x is an integer, and uses it
               for the interpreter and the  slave  command.  If  the  -safe
               switch is specified (or if the master interpreter is a  safe
               interpreter), the new slave interpreter will be created as a
               safe interpreter with limited functionality;  otherwise  the
               slave will include the full set of Tcl built-in commands and
               variables. The -- switch can be used  to  mark  the  end  of
               switches; it may be needed if path is an unusual value  such
               as -safe. The result of the command is the name of  the  new
               interpreter. The name of a slave interpreter must be  unique
               among all the slaves for its master; an error  occurs  if  a
               slave interpreter by the given name already exists  in  this
               master. 
          interp delete ?path ...?
               Deletes zero or more interpreters given by the optional path
               arguments, and for each interpreter,  it  also  deletes  its
               slaves. The command also deletes the slave command for  each
               interpreter deleted. For each  path    argument,    if    no
               interpreter by that  name  exists,  the  command  raises  an
               error. 
          interp eval path arg ?arg ...?
               This command concatenates all of the arg  arguments  in  the
               same fashion as  the  concat  command,  then  evaluates  the
               resulting string as a Tcl script in  the  slave  interpreter
               identified by path. The result of this evaluation (including
               error  information  such  as  the  errorInfo  and  errorCode
               variables, if an error occurs) is returned to  the  invoking
               interpreter. 
          interp exists path
               Returns 1 if a  slave  interpreter  by  the  specified  path
               exists in this master, 0 otherwise. If path is omitted,  the
               invoking interpreter is used.
          interp expose path hiddenName ?exposedCmdName?
               Makes the  hidden  command  hiddenName  exposed,  eventually
               bringing it back under a new exposedCmdName name (this  name
               is currently accepted only if it  is  a  valid  global  name
               space name without any ::), in the  interpreter  denoted  by
               path. If an exposed command with the targetted name  already
               exists, this command fails. Hidden commands are explained in
               more detail in HIDDEN COMMANDS, below.
          interp hide path exposedCmdName ?hiddenCmdName?
               Makes the exposed command exposedCmdName hidden, renaming it
               to the hidden command hiddenCmdName,  or  keeping  the  same
               name if hiddenCmdName  is  not  given,  in  the  interpreter
               denoted by path. If a hidden command with the targetted name
               already exists, this  command    fails.    Currently    both
               exposedCmdName and hiddenCmdName can not  contain  namespace
               qualifiers, or an error is raised. Commands to be hidden  by
               interp hide are looked up in the global  namespace  even  if
               the current namespace is not the global one.  This  prevents
               slaves from fooling a master  interpreter  into  hiding  the
               wrong command, by making the current namespace be  different
               from the global one. Hidden commands are explained  in  more
               detail in HIDDEN COMMANDS, below.
          interp hidden path
               Returns a list of the names of all hidden  commands  in  the
               interpreter identified by path.
          interp invokehidden path ?-global? hiddenCmdName ?arg ...?
               Invokes the hidden command hiddenCmdName with the  arguments
               supplied in the  interpreter    denoted    by    path.    No
               substitutions or evaluation are applied to the arguments. If
               the -global flag is present, the hidden command  is  invoked
               at the global level in the target interpreter; otherwise  it
               is invoked at the current call frame and  can  access  local
               variables in that and outer call frames. Hidden commands are
               explained in more detail in HIDDEN COMMANDS, below.
          interp issafe ?path?
               Returns 1 if the interpreter  identified  by  the  specified
               path is safe, 0 otherwise.
          interp marktrusted path
               Marks the interpreter identified by path  as  trusted.  Does
               not expose the hidden commands. This  command  can  only  be
               invoked from a  trusted  interpreter.  The  command  has  no
               effect if the interpreter  identified  by  path  is  already
               trusted. 
          interp share srcPath channelId destPath
               Causes the IO channel  identified  by  channelId  to  become
               shared between the interpreter identified by srcPath and the
               interpreter identified by destPath. Both  interpreters  have
               the same permissions on the IO  channel.  Both  interpreters
               must close  it  to  close  the  underlying  IO  channel;  IO
               channels accessible  in  an  interpreter  are  automatically
               closed when an interpreter is destroyed.
          interp slaves ?path?
               Returns a Tcl list of the names    of    all    the    slave
               interpreters associated with the interpreter  identified  by
               path. If path is omitted, the invoking interpreter is used.
          interp target path alias
               Returns a Tcl list describing the target interpreter for  an
               alias. The alias is specified with an interpreter  path  and
               source command name, just as in interp alias above. The name
               of the target interpreter  is  returned  as  an  interpreter
               path, relative to the invoking interpreter.  If  the  target
               interpreter for the alias is the invoking  interpreter  then
               an empty list is returned. If the target interpreter for the
               alias  is  not  the  invoking  interpreter  or  one  of  its
               descendants then an error is generated. The  target  command
               does not have to be defined at the time of this invocation.
          interp transfer srcPath channelId destPath
               Causes the IO channel  identified  by  channelId  to  become
               available in the  interpreter  identified  by  destPath  and
               unavailable in the interpreter identified by srcPath.

SLAVE COMMAND
     For each slave interpreter created with the interp command, a new  Tcl
     command is created in the master interpreter with the same name as the
     new interpreter. This command may be used to invoke various operations
     on the interpreter. It has the following general form:  slave  command
     ?arg arg ...? Slave is the name of the interpreter,  and  command  and
     the args determine the exact behavior of the command. The valid  forms
     of this command are:
          slave aliases
               Returns a Tcl list whose elements are the names of  all  the
               aliases in slave. The names returned are the  srcCmd  values
               used when the aliases were created (which  may  not  be  the
               same as the current names of the commands, if they have been
               renamed). 
          slave alias srcCmd
               Returns a Tcl list whose elements are the targetCmd and args
               associated with the alias named srcCmd (all of these are the
               values specified when the alias was created; it is  possible
               that the actual source command in  the  slave  is  different
               from srcCmd if it was renamed).
          slave alias srcCmd {}
               Deletes the alias  for  srcCmd  in  the  slave  interpreter.
               srcCmd refers to the name under which the alias was created;
               if the source command has been renamed, the renamed  command
               will be deleted.
          slave alias srcCmd targetCmd ?arg ..?
               Creates an alias such that whenever  srcCmd  is  invoked  in
               slave, targetCmd is invoked in the master. The arg arguments
               will be passed to targetCmd   as    additional    arguments,
               prepended before any arguments passed in the  invocation  of
               srcCmd. See ALIAS INVOCATION below for details.
          slave eval arg ?arg ..?
               This command concatenates all of the arg  arguments  in  the
               same fashion as  the  concat  command,  then  evaluates  the
               resulting string as a Tcl script in  slave.  The  result  of
               this evaluation (including error  information  such  as  the
               errorInfo and errorCode variables, if an  error  occurs)  is
               returned to the invoking interpreter.
          slave expose hiddenName ?exposedCmdName?
               This command exposes the    hidden    command    hiddenName,
               eventually bringing it back under a new exposedCmdName  name
               (this name is currently accepted  only  if  it  is  a  valid
               global name space name without any  ::),  in  slave.  If  an
               exposed command with the targetted name already exists, this
               command fails. For more  details  on  hidden  commands,  see
               HIDDEN COMMANDS, below.
          slave hide exposedCmdName ?hiddenCmdName?
               This  command  hides  the  exposed  command  exposedCmdName,
               renaming it to the hidden command hiddenCmdName, or  keeping
               the same name if the the argument is not given, in the slave
               interpreter. If a hidden command  with  the  targetted  name
               already exists, this  command    fails.    Currently    both
               exposedCmdName and hiddenCmdName can not  contain  namespace
               qualifiers, or an error is raised. Commands to be hidden are
               looked up in  the  global  namespace  even  if  the  current
               namespace is not the global one. This prevents  slaves  from
               fooling a master interpreter into hiding the wrong  command,
               by making the current namespace be different from the global
               one.  For  more  details  on  hidden  commands,  see  HIDDEN
               COMMANDS, below.
          slave hidden
               Returns a list of the names of all hidden commands in slave.
                
          slave invokehidden ?-global hiddenName ?arg ..?
               This command invokes the hidden command hiddenName with  the
               supplied arguments, in   slave.    No    substitutions    or
               evaluations are applied to the  arguments.  If  the  -global
               flag is given, the command is invoked at the global level in
               the slave; otherwise it is invoked at the current call frame
               and can access local variables in that or outer call frames.
               For more details on hidden commands,  see  HIDDEN  COMMANDS,
               below. 
          slave issafe
               Returns 1 if the slave interpreter is safe, 0 otherwise.
          slave marktrusted
               Marks the slave interpreter as trusted. Can only be  invoked
               by a trusted interpreter. This command does not  expose  any
               hidden commands in the slave interpreter. The command has no
               effect if the slave is already trusted.

SAFE INTERPRETERS
     A safe interpreter is one with restricted functionality,  so  that  is
     safe to execute an arbitrary script from your worst enemy without fear
     of that script damaging the enclosing application or the rest of  your
     computing environment. In order to make an interpreter  safe,  certain
     commands and variables are removed from the interpreter. For  example,
     commands to create files on disk are removed, and the exec command  is
     removed, since it could be used to cause damage through  subprocesses.
     Limited access to  these  facilities  can  be  provided,  by  creating
     aliases to the master interpreter which    check    their    arguments
     carefully and provide restricted access to   a    safe    subset    of
     facilities. For example, file creation might  be    allowed    in    a
     particular subdirectory and subprocess invocation might be allowed for
     a carefully selected and fixed set of programs.
     A safe interpreter is created by specifying the -safe  switch  to  the
     interp create command.  Furthermore,  any  slave  created  by  a  safe
     interpreter will also be safe.
     A safe interpreter is  created  with  exactly  the  following  set  of
     built-in commands: after append array binary break  case  catch  clock
     close concat continue eof error eval  expr  fblocked  fcopy  fileevent
     flush for foreach format gets global history if incr info interp  join
     lappend lindex linsert list  llength  lrange  lreplace  lsearch  lsort
     namespace package pid proc puts read regexp regsub rename return  scan
     seek set split string subst switch tell  trace  unset  update  uplevel
     upvar variable vwait while The following commands are hidden by interp
     create when it creates a safe interpreter:  cd  exec  exit  fconfigure
     file glob load open pwd socket source  vwait  These  commands  can  be
     recreated later as Tcl procedures or aliases, or re-exposed by  interp
     expose. 
     In addition, the env variable is not present in  a  safe  interpreter,
     so it cannot share environment variables with other interpreters.  The
     env variable poses a security risk, because users can store  sensitive
     information in an environment variable. For example,  the  PGP  manual
     recommends storing the PGP private  key  protection  password  in  the
     environment  variable  PGPPASS.  Making  this  variable  available  to
     untrusted code executing in a safe interpreter would incur a  security
     risk. 
     If extensions are loaded  into  a  safe  interpreter,  they  may  also
     restrict their own functionality to eliminate unsafe commands.  For  a
     discussion of management of  extensions  for  safety  see  the  manual
     entries for Safe-Tcl and the load Tcl command.


ALIAS INVOCATION
     The alias mechanism has been carefully designed so that it can be used
     safely when an untrusted script is executing in a safe slave  and  the
     target of the alias is a trusted master. The most important  thing  in
     guaranteeing safety is to ensure  that  information  passed  from  the
     slave to the master is never evaluated or substituted in  the  master;
     if this were to occur, it would enable an evil script in the slave  to
     invoke arbitrary functions  in  the  master,  which  would  compromise
     security. 
     When the source for an alias is invoked in the slave interpreter,  the
     usual Tcl substitutions are performed when parsing that command. These
     substitutions are carried out in the source interpreter just  as  they
     would be for any  other  command  invoked  in  that  interpreter.  The
     command procedure for the  source  command  takes  its  arguments  and
     merges them with the targetCmd and args for the alias to create a  new
     array of arguments. If the words of srcCmd were ``srcCmd arg1 arg2 ...
     argN'', the new set of words will be ``targetCmd arg arg ... arg  arg1
     arg2 ... argN'', where targetCmd and args are the values supplied when
     the alias was created. TargetCmd is then  used  to  locate  a  command
     procedure in the target interpreter, and  that  command  procedure  is
     invoked with the new set of arguments. An error occurs if there is  no
     command named targetCmd  in  the  target  interpreter.  No  additional
     substitutions are performed on the words: the target command procedure
     is invoked directly, without going through the normal  Tcl  evaluation
     mechanism. Substitutions are thus performed on each word exactly once:
     targetCmd and args were substituted  when  parsing  the  command  that
     created the alias, and arg1 - argN are substituted  when  the  alias's
     source command is parsed in the source interpreter.
     When writing the targetCmds for aliases in safe  interpreters,  it  is
     very important that the arguments to that command never  be  evaluated
     or substituted, since this would provide an escape  mechanism  whereby
     the slave interpreter could execute arbitrary code in the master. This
     in turn would compromise the security of the system.


HIDDEN COMMANDS
     Safe interpreters greatly restrict the functionality available to  Tcl
     programs executing within them. Allowing the untrusted Tcl program  to
     have direct access to this functionality is unsafe, because it can  be
     used for a variety of attacks on the environment. However,  there  are
     times when there is a legitimate need    to    use    the    dangerous
     functionality in the context of the  safe  interpreter.  For  example,
     sometimes a program must be  sourced  into  the  interpreter.  Another
     example is Tk, where windows are bound to the hierarchy of windows for
     a specific interpreter; some  potentially  dangerous  functions,  e.g.
     window management, must be  performed  on  these  windows  within  the
     interpreter context.
     The interp command provides a solution to this problem in the form  of
     hidden commands. Instead of removing the dangerous  commands  entirely
     from a safe interpreter, these commands  are  hidden  so  they  become
     unavailable to Tcl scripts executing in the interpreter. However, such
     hidden commands can be invoked by any trusted  ancestor  of  the  safe
     interpreter, in the context of  the  safe  interpreter,  using  interp
     invoke. Hidden commands and exposed commands reside in  separate  name
     spaces. It is possible to define  a  hidden  command  and  an  exposed
     command by the same name within one interpreter.
     Hidden commands in a slave interpreter can be invoked in the  body  of
     procedures called in the master during alias invocation. For  example,
     an alias for source could be created in a slave interpreter.  When  it
     is invoked in the slave interpreter, a  procedure  is  called  in  the
     master interpreter to check that the operation is allowable  (e.g.  it
     asks to source a  file  that  the  slave  interpreter  is  allowed  to
     access). The procedure then it invokes the hidden  source  command  in
     the slave interpreter to actually source in the contents of the  file.
     Note that two commands named source exist in  the  slave  interpreter:
     the alias, and the hidden command.
     Because a master interpreter may invoke a hidden command  as  part  of
     handling an alias invocation,  great  care  must  be  taken  to  avoid
     evaluating any arguments  passed  in  through  the  alias  invocation.
     Otherwise, malicious slave interpreters could cause a  trusted  master
     interpreter to execute dangerous commands on  their  behalf.  See  the
     section on ALIAS INVOCATION for a more  complete  discussion  of  this
     topic. To help avoid this problem, no substitutions or evaluations are
     applied to arguments of interp invokehidden.
     Safe interpreters  are  not  allowed  to  invoke  hidden  commands  in
     themselves or in their descendants. This  prevents  safe  slaves  from
     gaining access to hidden functionality in    themselves    or    their
     descendants. 
     The set of hidden commands in an interpreter can be manipulated  by  a
     trusted interpreter using interp expose and interp  hide.  The  interp
     expose command moves a hidden command to the set of  exposed  commands
     in the  interpreter  identified  by  path,  potentially  renaming  the
     command in the process. If an exposed command by  the  targetted  name
     already exists, the operation fails. Similarly, interp hide  moves  an
     exposed command to the set of hidden  commands  in  that  interpreter.
     Safe interpreters are not allowed to move commands between the set  of
     hidden and exposed commands, in    either    themselves    or    their
     descendants. 
     Currently, the names  of  hidden  commands  cannot  contain  namespace
     qualifiers, and you must first rename a command in a namespace to  the
     global namespace before you can hide it.  Commands  to  be  hidden  by
     interp hide are looked up in the global namespace even if the  current
     namespace is not the global one. This prevents slaves from  fooling  a
     master interpreter into  hiding  the  wrong  command,  by  making  the
     current namespace be different from the global one.

CREDITS 
     This mechanism is based  on  the  Safe-Tcl  prototype  implemented  by
     Nathaniel Borenstein and Marshall Rose.


SEE ALSO
     load, safe, Tcl_CreateSlave

KEYWORDS 
     alias, master interpreter, safe interpreter, slave interpreter





_________________________________________________________________

NAME
     join - Create a string by joining together list elements

SYNOPSIS
	join list ?joinString?

_________________________________________________________________

DESCRIPTION 
     The list argument must be a valid Tcl list. This command  returns  the
     string formed by joining all of the elements  of  list  together  with
     joinString separating each adjacent pair of elements.  The  joinString
     argument defaults to a space character.


SEE ALSO
     list, lappend

KEYWORDS 
     element, join, list, separator






_________________________________________________________________

NAME
     lappend - Append list elements onto a variable

SYNOPSIS
	lappend varName ?value value value ...?

_________________________________________________________________

DESCRIPTION 
     This command treats the variable  given  by  varName  as  a  list  and
     appends each of the  value  arguments  to  that  list  as  a  separate
     element, with spaces between elements. If varName doesn't exist, it is
     created as a list with elements given by the value arguments.  Lappend
     is similar to append except that  the  values  are  appended  as  list
     elements rather than raw text.  This  command  provides  a  relatively
     efficient way to build up large lists. For example, ``lappend  a  $b''
     is much more efficient than ``set a [concat $a [list $b]]'' when $a is
     long. 


SEE ALSO
     list, lindex, linsert, llength, lsort, lrange

KEYWORDS 
     append, element, list, variable






_________________________________________________________________

NAME
     auto_execok, auto_import, auto_load,  auto_mkindex,  auto_mkindex_old,
     auto_qualify, auto_reset, tcl_findLibrary,   parray,    tcl_endOfWord,
     tcl_startOfNextWord,   tcl_startOfPreviousWord,    tcl_wordBreakAfter,
     tcl_wordBreakBefore - standard library of Tcl procedures

SYNOPSIS
	auto_execok cmd
	auto_import pattern
	auto_load cmd
	auto_mkindex dir pattern pattern ...
	auto_mkindex_old dir pattern pattern ...
	auto_qualify command namespace
	auto_reset
	tcl_findLibrary basename version patch initScript enVarName varName
	parray arrayName
	tcl_endOfWord str start
	tcl_startOfNextWord str start
	tcl_startOfPreviousWord str start
	tcl_wordBreakAfter str start
	tcl_wordBreakBefore str start

INTRODUCTION 
     Tcl includes a library of  Tcl    procedures    for    commonly-needed
     functions. The procedures defined in the Tcl library are generic  ones
     suitable for use by many different applications. The location  of  the
     Tcl library is returned by the info library command.  In  addition  to
     the Tcl library, each application will normally have its  own  library
     of support procedures  as  well;  the  location  of  this  library  is
     normally given by the value of the $app_library global variable, where
     app is the name of the application. For example, the location  of  the
     Tk library is kept in the variable $tk_library.
     To access the procedures in the Tcl  library,  an  application  should
     source the file init.tcl in the library,  for  example  with  the  Tcl
     command source [file join [info  library]  init.tcl]  If  the  library
     procedure  Tcl_Init  is  invoked  from  an  application's  Tcl_AppInit
     procedure, this happens  automatically.  The  code  in  init.tcl  will
     define the unknown procedure and arrange for the other  procedures  to
     be loaded on-demand using the auto-load mechanism defined below.


COMMAND PROCEDURES
     The following procedures are provided in the Tcl library:
          auto_execok cmd
               Determines whether there is  an  executable  file  or  shell
               builtin by the name  cmd.  If  so,  it  returns  a  list  of
               arguments to be passed to exec  to  execute  the  executable
               file or shell builtin named by cmd. If not,  it  returns  an
               empty string. This command examines the directories  in  the
               current search path (given by the PATH environment variable)
               in its search for an executable file named cmd.  On  Windows
               platforms, the search is expanded with the same  directories
               and file extensions as used  by  exec.  Auto_exec  remembers
               information  about  previous  searches  in  an  array  named
               auto_execs; this avoids the path search in future calls  for
               the same cmd. The command auto_reset may be  used  to  force
               auto_execok to forget its cached information.
          auto_import pattern
               Auto_import is invoked during namespace import to see if the
               imported commands specified by pattern    reside    in    an
               autoloaded library. If so, the commands are loaded  so  that
               they will be available to the interpreter for  creating  the
               import links. If the commands do not reside in an autoloaded
               library, auto_import does nothing.
          auto_load cmd
               This command attempts to  load  the  definition  for  a  Tcl
               command named cmd. To do  this,  it  searches  an  auto-load
               path, which is a  list  of  one  or  more  directories.  The
               auto-load path is given by the global variable $auto_path if
               it exists. If there is  no  $auto_path  variable,  then  the
               TCLLIBPATH environment  variable  is  used,  if  it  exists.
               Otherwise the  auto-load  path  consists  of  just  the  Tcl
               library directory. Within each directory  in  the  auto-load
               path there must be a file tclIndex  that  describes  one  or
               more commands defined in that  directory  and  a  script  to
               evaluate to load each of the  commands.  The  tclIndex  file
               should be generated with the auto_mkindex command. If cmd is
               found in an index  file,  then  the  appropriate  script  is
               evaluated to  create  the  command.  The  auto_load  command
               returns 1 if  cmd  was  successfully  created.  The  command
               returns 0 if there was no index entry  for  cmd  or  if  the
               script  didn't  actually  define  cmd  (e.g.  because  index
               information is out  of  date).  If  an  error  occurs  while
               processing the script, then that    error    is    returned.
               Auto_load only reads the index information once and saves it
               in the array auto_index; future calls to auto_load check for
               cmd in the array rather than re-reading the index files. The
               cached index information may be  deleted  with  the  command
               auto_reset. This will force the next  auto_load  command  to
               reload the index database from disk.
          auto_mkindex dir pattern pattern ...
               Generates an  index  suitable  for  use  by  auto_load.  The
               command searches dir for all files whose names match any  of
               the pattern  arguments  (matching  is  done  with  the  glob
               command), generates an index of all    the    Tcl    command
               procedures defined in all the matching files, and stores the
               index information in a file named tclIndex  in  dir.  If  no
               pattern is given a pattern of *.tcl  will  be  assumed.  For
               example, the command auto_mkindex foo *.tcl
               will read  all  the  .tcl  files  in  subdirectory  foo  and
               generate a new index file foo/tclIndex.
               Auto_mkindex parses the Tcl scripts by sourcing them into  a
               slave interpreter and  monitoring  the  proc  and  namespace
               commands that are executed.  Extensions    can    use    the
               (undocumented) auto_mkindex_parser package to register other
               commands that can contribute to  the  auto_load  index.  You
               will have to read through auto.tcl to see how this works.
               Auto_mkindex_old parses the  Tcl  scripts  in  a  relatively
               unsophisticated way: if any line contains the word  proc  as
               its first characters then it is assumed to  be  a  procedure
               definition and the next word of the line  is  taken  as  the
               procedure's name. Procedure definitions that don't appear in
               this way (e.g. they have spaces before the proc) will not be
               indexed. If your script contains "dangerous" code,  such  as
               global initialization code or procedure names  with  special
               characters like $, *, [ or ],   you    are    safer    using
               auto_mkindex_old. 
          auto_reset 
               Destroys all  the  information  cached  by  auto_execok  and
               auto_load. This information will be re-read  from  disk  the
               next time it is needed. Auto_reset    also    deletes    any
               procedures listed in the  auto-load  index,  so  that  fresh
               copies of them will be loaded the  next  time  that  they're
               used. 
          auto_qualify command namespace
               Computes a list of fully qualified names for  command.  This
               list mirrors the path a standard Tcl interpreter follows for
               command lookups: first it  looks  for  the  command  in  the
               current namespace, and then in   the    global    namespace.
               Accordingly, if command is relative and namespace is not ::,
               the list  returned  has  two  elements:  command  scoped  by
               namespace,  as  if  it  were  a  command  in  the  namespace
               namespace; and command as if it were a command in the global
               namespace. Otherwise, if  either  command  is  absolute  (it
               begins with ::), or namespace is ::, the list contains  only
               command as if it were a command in the global namespace.
               Auto_qualify is used by the auto-loading facilities in  Tcl,
               both for  producing    auto-loading    indexes    such    as
               pkgIndex.tcl, and for performing the actual auto-loading  of
               functions at runtime.
          tcl_findLibrary basename version patch    initScript    enVarName
          varName 
               This is a standard search procedure for  use  by  extensions
               during their initialization. They  call  this  procedure  to
               look for their script   library    in    several    standard
               directories. The last component of the name of  the  library
               directory is normally basenameversion (e.g., tk8.0), but  it
               might be  "library"  when  in  the  build  hierarchies.  The
               initScript file will be sourced into the interpreter once it
               is found. The directory in  which  this  file  is  found  is
               stored into the global variable varName. If this variable is
               already defined (e.g., by C    code    during    application
               initialization) then no searching  is  done.  Otherwise  the
               search looks in these directories: the  directory  named  by
               the environment variable  enVarName;  relative  to  the  Tcl
               library directory; relative to the executable  file  in  the
               standard installation bin or bin/arch directory; relative to
               the executable file in the current build tree;  relative  to
               the executable file in a parallel build tree.
          parray arrayName
               Prints on standard output the names and values  of  all  the
               elements in the array arrayName. ArrayName must be an  array
               accessible to the caller of parray. It may be  either  local
               or global.
          tcl_endOfWord str start
               Returns the index of the  first  end-of-word  location  that
               occurs after a starting index start in the  string  str.  An
               end-of-word location is defined to  be  the  first  non-word
               character following  the  first  word  character  after  the
               starting point. Returns -1 if there are no more  end-of-word
               locations after the starting point. See the  description  of
               tcl_wordchars and tcl_nonwordchars below for more details on
               how Tcl determines which characters are word characters.
          tcl_startOfNextWord str start
               Returns the index of the first start-of-word  location  that
               occurs after a starting index start in  the  string  str.  A
               start-of-word location is  defined  to  be  the  first  word
               character following a  non-word  character.  Returns  -1  if
               there are no more start-of-word locations after the starting
               point. 
          tcl_startOfPreviousWord str start
               Returns the index of the first start-of-word  location  that
               occurs before a starting index  start  in  the  string  str.
               Returns -1 if there  are  no  more  start-of-word  locations
               before the starting point.
          tcl_wordBreakAfter str start
               Returns the index of  the  first  word  boundary  after  the
               starting index start in the string str. Returns -1 if  there
               are no more boundaries after the starting point in the given
               string. The index returned refers to the second character of
               the pair that comprises a boundary.
          tcl_wordBreakBefore str start
               Returns the index of the  first  word  boundary  before  the
               starting index start in the string str. Returns -1 if  there
               are no more boundaries before  the  starting  point  in  the
               given string.  The  index  returned  refers  to  the  second
               character of the pair that comprises a boundary.

VARIABLES 
     The following global variables are defined or used by  the  procedures
     in the Tcl library:
          auto_execs 
               Used by auto_execok  to  record  information  about  whether
               particular commands exist as executable files.
          auto_index 
               Used by auto_load to save the index  information  read  from
               disk. 
          auto_noexec 
               If set to any  value,  then  unknown  will  not  attempt  to
               auto-exec any commands.
          auto_noload 
               If set to any  value,  then  unknown  will  not  attempt  to
               auto-load any commands.
          auto_path 
               If set, then  it  must  contain  a  valid  Tcl  list  giving
               directories to  search  during  auto-load  operations.  This
               variable is initialized during startup to contain, in order:
               the directories listed in   the    TCLLIBPATH    environment
               variable, the directory named by the $tcl_library  variable,
               the parent directory of $tcl_library, the directories listed
               in the $tcl_pkgPath variable.
          env(TCL_LIBRARY) 
               If set, then it specifies  the  location  of  the  directory
               containing library scripts (the value of this variable  will
               be  assigned  to  the  tcl_library  variable  and  therefore
               returned by the command  info  library).  If  this  variable
               isn't set then a default value is used.
          env(TCLLIBPATH) 
               If set, then  it  must  contain  a  valid  Tcl  list  giving
               directories to  search    during    auto-load    operations.
               Directories must be specified in Tcl format,  using  "/"  as
               the path separator, regardless of platform. This variable is
               only used when initializing the auto_path variable.
          tcl_nonwordchars 
               This variable contains a regular expression that is used  by
               routines like tcl_endOfWord to identify whether a  character
               is part  of  a  word  or  not.  If  the  pattern  matches  a
               character, the character is  considered  to  be  a  non-word
               character. On Windows platforms, spaces, tabs, and  newlines
               are considered non-word characters. Under  Unix,  everything
               but numbers, letters and underscores are considered non-word
               characters. 
          tcl_wordchars 
               This variable contains a regular expression that is used  by
               routines like tcl_endOfWord to identify whether a  character
               is part  of  a  word  or  not.  If  the  pattern  matches  a
               character, the character is considered to    be    a    word
               character. On Windows platforms, words are comprised of  any
               character that is not a space, tab, or newline. Under  Unix,
               words are comprised of numbers, letters or underscores.
          unknown_pending 
               Used by unknown to record the command(s)  for  which  it  is
               searching.  It  is  used  to  detect  errors  where  unknown
               recurses on itself infinitely. The variable is unset  before
               unknown returns.

SEE ALSO
     info, re_syntax

KEYWORDS 
     auto-exec, auto-load, library, unknown, word, whitespace






_________________________________________________________________

NAME
     lindex - Retrieve an element from a list

SYNOPSIS
	lindex list index

_________________________________________________________________

DESCRIPTION 
     This command treats list as  a  Tcl  list  and  returns  the  index'th
     element from it (0 refers to  the  first  element  of  the  list).  In
     extracting the element, lindex  observes  the  same  rules  concerning
     braces and quotes and backslashes  as  the  Tcl  command  interpreter;
     however, variable substitution and command substitution do not  occur.
     If index is negative or  greater  than  or  equal  to  the  number  of
     elements in value, then an empty string is returned. If index has  the
     value end, it refers to the last element in the list, and  end-integer
     refers to the last element in the list  minus  the  specified  integer
     offset. 


SEE ALSO
     list, lappend, linsert, llength, lsearch, lsort, lrange, lreplace

KEYWORDS 
     element, index, list






_________________________________________________________________

NAME
     linsert - Insert elements into a list

SYNOPSIS
	linsert list index element ?element element ...?

_________________________________________________________________

DESCRIPTION 
     This command produces a new list from list by  inserting  all  of  the
     element arguments just  before  the  indexth  element  of  list.  Each
     element argument will become a separate element of the  new  list.  If
     index is less than or  equal  to  zero,  then  the  new  elements  are
     inserted at the beginning of the list. If index has the value end,  or
     if it is greater than or equal to the number of elements in the  list,
     then the new elements are appended to the list. end-integer refers  to
     the last element in the list minus the specified integer offset.


SEE ALSO
     list, lappend, llength

KEYWORDS 
     element, insert, list






_________________________________________________________________

NAME
     list - Create a list

SYNOPSIS
	list ?arg arg ...?

_________________________________________________________________

DESCRIPTION 
     This command returns a list comprised of all the  args,  or  an  empty
     string if no args are specified. Braces and backslashes get  added  as
     necessary, so that the index command may be  used  on  the  result  to
     re-extract the original arguments, and also so that eval may  be  used
     to execute the resulting list, with arg1 comprising the command's name
     and the other args comprising its arguments.  List  produces  slightly
     different results than concat: concat removes one  level  of  grouping
     before forming the list, while list works directly from  the  original
     arguments. For example, the command list a b {c d e} {f  {g  h}}  will
     return a b {c d e} {f {g h}} while concat with the same arguments will
     return a b c d e f {g h}

SEE ALSO
     lappend, lindex, linsert, llength, lsearch, lsort, lrange, lreplace

KEYWORDS 
     element, list






_________________________________________________________________

NAME
     llength - Count the number of elements in a list

SYNOPSIS
	llength list

_________________________________________________________________

DESCRIPTION 
     Treats list as a list and returns a decimal string giving  the  number
     of elements in it.


SEE ALSO
     list, lindex, lrange

KEYWORDS 
     element, list, length






_________________________________________________________________

NAME
     load - Load machine code and initialize new commands.

SYNOPSIS
	load fileName
	load fileName packageName
	load fileName packageName interp

_________________________________________________________________

DESCRIPTION 
     This command loads binary code from  a  file  into  the  application's
     address space and calls an initialization procedure in the package  to
     incorporate it into an interpreter. fileName is the name of  the  file
     containing the code; its exact form varies from system to  system  but
     on most systems it is a shared library,  such  as  a  .so  file  under
     Solaris or a DLL  under  Windows.  packageName  is  the  name  of  the
     package, and  is  used  to  compute  the  name  of  an  initialization
     procedure. interp is the path name of the interpreter  into  which  to
     load the package (see the interp manual entry for details); if  interp
     is omitted, it defaults to the interpreter in which the  load  command
     was invoked.
     Once the file has been loaded into the  application's  address  space,
     one of two initialization procedures will be invoked in the new  code.
     Typically the initialization procedure will add new commands to a  Tcl
     interpreter. The name of the initialization procedure is determined by
     packageName and whether or not the target interpreter is a  safe  one.
     For normal interpreters the name of the initialization procedure  will
     have the form pkg_Init, where pkg is the same  as  packageName  except
     that the first letter is converted to upper case and all other letters
     are converted to lower case. For example, if  packageName  is  foo  or
     FOo, the initialization procedure's name will be Foo_Init.
     If the target interpreter is a safe interpreter, then the name of  the
     initialization procedure will be pkg_SafeInit instead of pkg_Init. The
     pkg_SafeInit function should be written carefully,    so    that    it
     initializes the  safe  interpreter  only  with  partial  functionality
     provided by the package that is safe for use by  untrusted  code.  For
     more information on Safe-Tcl, see the safe manual entry.
     The initialization  procedure  must  match  the  following  prototype:
     typedef int Tcl_PackageInitProc(Tcl_Interp  *interp);    The    interp
     argument identifies the interpreter in which  the  package  is  to  be
     loaded. The initialization procedure must return TCL_OK  or  TCL_ERROR
     to indicate whether or not it completed successfully; in the event  of
     an error it should set the interpreter's result to point to  an  error
     message. The result of the load command will be the result returned by
     the initialization procedure.
     The actual loading of a file will only be done once for each  fileName
     in an application.  If  a  given  fileName  is  loaded  into  multiple
     interpreters, then the first load will load  the  code  and  call  the
     initialization procedure;   subsequent    loads    will    call    the
     initialization procedure without loading the code  again.  It  is  not
     possible to unload or reload a package.
     The load command also supports packages  that  are  statically  linked
     with the application,  if  those  packages  have  been  registered  by
     calling the Tcl_StaticPackage  procedure.  If  fileName  is  an  empty
     string, then packageName must be specified.
     If packageName is omitted or specified as an empty string,  Tcl  tries
     to guess the name of the package. This  may  be  done  differently  on
     different platforms. The default guess, which is  used  on  most  UNIX
     platforms, is to take the last element  of  fileName,  strip  off  the
     first three  characters  if  they  are  lib,  and  use  any  following
     alphabetic and underline characters as the module name.  For  example,
     the command load libxyz4.2.so uses the module name xyz and the command
     load bin/last.so {} uses the module name last.
     If fileName is an empty string, then packageName  must  be  specified.
     The load command first searches for a statically loaded  package  (one
     that has been registered by calling the  Tcl_StaticPackage  procedure)
     by that name; if one is found, it is used. Otherwise, the load command
     searches for a dynamically loaded package by that name, and uses it if
     it is  found.  If  several  different  files  have  been  loaded  with
     different versions of the package, Tcl picks the file that was  loaded
     first. 


PORTABILITY ISSUES
          Windows 
               When a load fails with "library not found" error, it is also
               possible that a dependent library was not found. To see  the
               dependent libraries, type ``dumpbin -imports <dllname>''  in
               a DOS console to see what  the  library  must  import.  When
               loading a DLL in the current directory, Windows will  ignore
               ``./'' as a path specifier and use  a  search  heuristic  to
               find the DLL instead. To avoid this, load the DLL with  load
               [file join [pwd] mylib.DLL]
BUGS 
     If the same file is loaded by different fileNames, it will  be  loaded
     into the process's address space multiple times. The behavior of  this
     varies from system to system (some systems may  detect  the  redundant
     loads, others may not).


SEE ALSO
     info sharedlibextension, Tcl_StaticPackage, safe

KEYWORDS 
     binary code, loading, safe interpreter, shared library





_________________________________________________________________

NAME
     lrange - Return one or more adjacent elements from a list

SYNOPSIS
	lrange list first last

_________________________________________________________________

DESCRIPTION 
     List must be a valid Tcl list. This command will  return  a  new  list
     consisting of elements first through last, inclusive.  First  or  last
     may be end (or any abbreviation of it) to refer to the last element of
     the list. If first is less than zero, it is  treated  as  if  it  were
     zero. If last is greater than or equal to the number  of  elements  in
     the list, then it is treated as if it were end. If  first  is  greater
     than last then an empty string is returned. Note: ``lrange list  first
     first'' does not always produce  the  same  result  as  ``lindex  list
     first'' (although it often does for simple fields that aren't enclosed
     in braces); it does, however, produce  exactly  the  same  results  as
     ``list [lindex list first]''


SEE ALSO
     lappend, lindex, linsert, list, llength, lreplace

KEYWORDS 
     element, list, range, sublist






_________________________________________________________________

NAME
     lreplace - Replace elements in a list with new elements

SYNOPSIS
	lreplace list first last ?element element ...?

_________________________________________________________________

DESCRIPTION 
     lreplace returns a new list formed by replacing one or  more  elements
     of list with the element arguments. first and last specify  the  first
     and last index of the range of elements to replace. 0  refers  to  the
     first element of the list, and end (or any abbreviation of it) may  be
     used to refer to the last element of the list. If list is empty,  then
     first and last are ignored.

If first is less than zero, it is considered to refer to the
first element of the list.  For non-empty lists, the element indicated
by first must exist.

If last is less than zero but greater than first, then any
specified elements will be prepended to the list.  If last is
less than first then no elements are deleted; the new elements
are simply inserted before first.

The element arguments specify zero or more new arguments to
be added to the list in place of those that were deleted.
Each element argument will become a separate element of
the list.  If no element arguments are specified, then the elements
between first and last are simply deleted.  If list
is empty, any element arguments are added to the end of the list.


SEE ALSO
     lappend, lindex, linsert, list, llength, lrange, lsearch, lsort

KEYWORDS 
     element, list, replace






_________________________________________________________________

NAME
     lsearch - See if a list contains a particular element

SYNOPSIS
	lsearch ?options? list pattern

_________________________________________________________________

DESCRIPTION 
     This command searches the elements of list  to  see  if  one  of  them
     matches pattern. If so, the command returns the  index  of  the  first
     matching element. If not, the command returns -1. The option arguments
     indicates how the elements of the  list  are  to  be  matched  against
     pattern and it must have one of the following values:
          -ascii 
               The list elements are to be examined as ASCII strings.  This
               option is only meaningful when used with -exact or -sorted.
          -decreasing 
               The list elements  are  sorted  in  decreasing  order.  This
               option is only meaningful when used with -sorted.
          -dictionary 
               The list elements are to be compared using  dictionary-style
               comparisons. This option is only meaningful when  used  with
               -exact or -sorted.
          -exact 
               The list element must contain exactly  the  same  string  as
               pattern. 
          -increasing 
               The list elements  are  sorted  in  increasing  order.  This
               option is only meaningful when used with -sorted.
          -integer 
               The list elements are  to  be  compared  as  integers.  This
               option is only meaningful when used with -exact or -sorted.
          -glob 
               Pattern is a glob-style pattern  which  is  matched  against
               each list element using the same rules as the  string  match
               command. 
          -real 
               The list elements  are  to  be  compared  as  floating-point
               values. This option is only meaningful when used with -exact
               or -sorted.
          -regexp 
               Pattern is treated  as  a  regular  expression  and  matched
               against each list element using the rules described  in  the
               re_syntax reference page.
          -sorted 
               The list elements are in sorted order.  If  this  option  is
               specified, lsearch  will  use  a  more  efficient  searching
               algorithm to search list. If no other options are specified,
               list is assumed to be sorted in  increasing  order,  and  to
               contain ASCII strings. This option cannot be used with -glob
               or -regexp.
     If option is omitted then it defaults to -glob. If more  than  one  of
     -exact, -glob, -regexp, and -sorted is specified, whichever option  is
     specified  last  takes  precendence.  If  more  than  one  of  -ascii,
     -dictionary, -integer and -real is  specified,  the  option  specified
     last takes precendence. If more than   one    of    -increasing    and
     -decreasing is specified, the option specified last takes precedence.


SEE ALSO
     lappend, lindex, linsert, list, llength, lrange, lreplace, lsort

KEYWORDS 
     list, match, pattern, regular expression, search, string






_________________________________________________________________

NAME
     lsort - Sort the elements of a list

SYNOPSIS
	lsort ?options? list

_________________________________________________________________

DESCRIPTION 
     This command sorts the elements of  list,  returning  a  new  list  in
     sorted order.  The  implementation  of  the  lsort  command  uses  the
     merge-sort algorithm which is a  stable  sort  that  has  O(n  log  n)
     performance characteristics.
     By  default  ASCII  sorting  is  used  with  the  result  returned  in
     increasing order.  However,  any  of  the  following  options  may  be
     specified before list to control  the    sorting    process    (unique
     abbreviations are accepted):
          -ascii 
               Use string comparison with ASCII collation  order.  This  is
               the default.
          -dictionary 
               Use dictionary-style comparison. This is the same as  -ascii
               except (a) case is ignored except as a tie-breaker  and  (b)
               if two strings contain embedded numbers, the numbers compare
               as integers, not characters.  For  example,  in  -dictionary
               mode, bigBoy sorts between  bigbang  and  bigboy,  and  x10y
               sorts between x9y and x11y.
          -integer 
               Convert list elements to   integers    and    use    integer
               comparison. 
          -real 
               Convert list  elements  to  floating-point  values  and  use
               floating comparison.
          -command command
               Use command as a comparison command.    To    compare    two
               elements, evaluate a Tcl script consisting of  command  with
               the two  elements  appended  as  additional  arguments.  The
               script should return an integer  less  than,  equal  to,  or
               greater than zero if the first element is to  be  considered
               less than, equal to, or    greater    than    the    second,
               respectively. 
          -increasing 
               Sort  the  list  in  increasing  order  (``smallest''  items
               first). This is the default.
          -decreasing 
               Sort the list in decreasing order (``largest'' items first).
                
          -index index
               If this option is specified, each of the  elements  of  list
               must itself be a proper  Tcl  sublist.  Instead  of  sorting
               based on whole sublists, lsort  will  extract  the  index'th
               element from each  sublist  and  sort  based  on  the  given
               element. The keyword end is allowed for the index to sort on
               the last sublist element. For example, lsort -integer -index
               1 {{First 24} {Second 18} {Third 30}}  returns  {Second  18}
               {First 24} {Third 30}. This option is  much  more  efficient
               than using -command to achieve the same effect.
          -unique 
               If this option is specified,  then  only  the  last  set  of
               duplicate elements found in the list will be retained.  Note
               that duplicates are determined relative  to  the  comparison
               used in the sort. Thus if -index 0 is used, {1 a} and {1  b}
               would be considered duplicates and only the second  element,
               {1 b}, would be retained.

SEE ALSO
     lappend, lindex, linsert, list, llength, lrange, lreplace, lsearch

KEYWORDS 
     element, list, order, sort







_________________________________________________________________

NAME
     memory - Control Tcl memory debugging capabilities.

SYNOPSIS
	memory option ?arg arg ...?
	

_________________________________________________________________

DESCRIPTION 
     The memory command gives the Tcl developer  control  of  Tcl's  memory
     debugging capabilities. The memory  command  has  several  suboptions,
     which are described below. It is only  available  when  Tcl  has  been
     compiled with memory debugging enabled (when TCL_MEM_DEBUG is  defined
     at compile time).
          memory info
               Produces a report containing the total allocations and frees
               since Tcl began, the current packets allocated (the  current
               number of calls to ckalloc not met by a  corresponding  call
               to ckfree), the current bytes  allocated,  and  the  maximum
               number of packets and bytes allocated.
          memory trace [on|off]
               Turns memory tracing on or off. When memory tracing  is  on,
               every call to ckalloc causes a line of trace information  to
               be written  to  stderr,  consisting  of  the  word  ckalloc,
               followed by the  address  returned,  the  amount  of  memory
               allocated, and the C filename and line number  of  the  code
               performing the allocation. For example:  ckalloc  40e478  98
               tclProc.c 1406 Calls  to  ckfree  are  traced  in  the  same
               manner. 
          memory validate [on|off]
               Turns memory validation on or off. When memory validation is
               enabled, on every call to ckalloc or ckfree, the guard zones
               are checked for every piece of memory currently in existence
               that was allocated by ckalloc. This has a large  performance
               impact and should only be used when overwrite  problems  are
               strongly suspected. The advantage   of    enabling    memory
               validation is that a guard zone overwrite can be detected on
               the first call to ckalloc  or  ckfree  after  the  overwrite
               occurred, rather than when  the  specific  memory  with  the
               overwritten guard zone(s) is freed,  which  may  occur  long
               after the overwrite occurred.
          memory trace_on_at_malloc count
               Enable  memory  tracing  after  count  ckalloc's  have  been
               performed.   For    example,    if    you    enter    memory
               trace_on_at_malloc 100, after the  100th  call  to  ckalloc,
               memory trace information will begin being displayed for  all
               allocations and frees. Since there can be a  lot  of  memory
               activity before a problem  occurs,  judicious  use  of  this
               option can reduce the slowdown caused by  tracing  (and  the
               amount of trace information produced), if you can identify a
               number of allocations that occur before the problem sets in.
               The current number of memory allocations that have  occurred
               since Tcl started is printed on a guard zone failure.
          memory break_on_malloc count
               After the count allocations have been  performed,  ckalloc's
               output  a  message  to  this  effect  and  that  it  is  now
               attempting to enter the C debugger. Tcl will  then  issue  a
               SIGINT signal against itself. If you are running Tcl under a
               C debugger, it should then enter the debugger command mode.
          memory display file
               Write a list  of  all  currently  allocated  memory  to  the
               specified file.

SEE ALSO
     ckalloc,    ckfree,    Tcl_ValidateAllMemory,    Tcl_DumpActiveMemory,
     TCL_MEM_DEBUG 

KEYWORDS 
     memory, debug






_________________________________________________________________

NAME
     msgcat - Tcl message catalog

SYNOPSIS
	::msgcat::mc src-string ?arg arg ...?
	::msgcat::mcmax ?src-string src-string ...?
	::msgcat::mclocale ?newLocale?
	::msgcat::mcpreferences
	::msgcat::mcload dirname
	::msgcat::mcset locale src-string ?translate-string?
	::msgcat::mcmset locale src-trans-list
	::msgcat::mcunknown locale src-string

_________________________________________________________________

DESCRIPTION 
     The msgcat package provides a set of functions that  can  be  used  to
     manage multi-lingual user interfaces. Text strings are  defined  in  a
     ``message catalog'' which is independent  from  the  application,  and
     which can be edited or localized  without  modifying  the  application
     source code. New languages or locales are provided  by  adding  a  new
     file to the message catalog.
     Use of the message catalog is optional by any application or  package,
     but is encouraged if the application or package wishes to  be  enabled
     for multi-lingual applications.


COMMANDS 
          ::msgcat::mc src-string ?arg arg ...?
               Returns a translation of src-string according to the  user's
               current locale. If additional arguments past src-string  are
               given, the format command is used    to    substitute    the
               additional arguments in the translation of src-string.
               ::msgcat::mc will search the messages   defined    in    the
               current namespace for a translation of src-string;  if  none
               is found, it will  search  in  the  parent  of  the  current
               namespace, and so on until it reaches the global  namespace.
               If no  translation  string  exists,  ::msgcat::mcunknown  is
               called and the string returned from  ::msgcat::mcunknown  is
               returned. 
     ::msgcat::mc is the main function used  to  localize  an  application.
     Instead of using an English string directly, an  applicaton  can  pass
     the English string through ::msgcat::mc and  use  the  result.  If  an
     application is written for a single language in this fashion, then  it
     is easy to add  support  for  additional  languages  later  simply  by
     defining new message catalog entries.
          ::msgcat::mcmax ?src-string src-string ...?
               Given several source strings,  ::msgcat::mcmax  returns  the
               length of the longest translated string. This is useful when
               designing  localized  GUI's,  which  may  require  that  all
               buttons, for example, be a fixed width (which  will  be  the
               width of the widest button).
          ::msgcat::mclocale ?newLocale?
               This function sets the locale to newLocale. If newLocale  is
               omitted, the  current  locale  is  returned,  otherwise  the
               current locale is  set  to  newLocale.  The  initial  locale
               defaults to the locale specified in the user's  environment.
               See LOCALE AND SUBLOCALE  SPECIFICATION    below    for    a
               description of the locale string format.
          ::msgcat::mcpreferences 
               Returns an ordered list of  the  locales  preferred  by  the
               user, based on the user's language specification.  The  list
               is ordered from most specific to least  preference.  If  the
               user has specified LANG=en_US_funky,  this  procedure  would
               return {en_US_funky en_US en}.
          ::msgcat::mcload dirname
               Searches the specified directory for files  that  match  the
               language specifications returned by ::msgcat::mcpreferences.
               Each file located is sourced. The    file    extension    is
               ``.msg''. The number of  message  files  which  matched  the
               specification and were loaded is returned.
          ::msgcat::mcset locale src-string ?translate-string?
               Sets the translation for src-string to  translate-string  in
               the specified locale. If translate-string is not  specified,
               src-string is used for   both.    The    function    returns
               translate-string. 
          ::msgcat::mcmset locale src-trans-list
               Sets the translation for multiple    source    strings    in
               src-trans-list in the specified locale. src-trans-list  must
               have  an  even  number  of  elements  and  is  in  the  form
               {src-string  translate-string  ?src-string  translate-string
               ...?} mcsetcat::mcmset  can  be  significantly  faster  than
               multiple invocations of msgcat::mcset. The function  returns
               the number of translations set.
          ::msgcat::mcunknown locale src-string
               This routine is called by ::msgcat::mc in the  case  when  a
               translation for src-string is not  defined  in  the  current
               locale. The default action is  to  return  src-string.  This
               procedure can be redefined by the application,  for  example
               to log error messages for  each    unknown    string.    The
               ::msgcat::mcunknown procedure is invoked at the  same  stack
               context as the call to  ::msgcat::mc.  The  return  vaue  of
               ::msgcat::mcunknown is used as the return vaue for the  call
               to ::msgcat::mc.

LOCALE AND SUBLOCALE SPECIFICATION
     The locale is specified by a locale string. The locale string consists
     of a  language  code,  an  optional  country  code,  and  an  optional
     system-specific  code,  each  separated  by  ``_''.  The  country  and
     language codes are specified in standards ISO-639  and  ISO-3166.  For
     example, the locale ``en'' specifies English  and  ``en_US''  specifes
     U.S. English.
     The locale defaults to the value in env(LANG) at the time  the  msgcat
     package is loaded. On Windows, if env(LANG) is not  set,  the  package
     will attempt to extract locale information from the  registry.  If  it
     cannot find this  information  in  the  registry,  or  on  non-Windows
     platforms when env(LANG) is not defined, the locale defaults to ``C''.
      
     When a locale is specified by the user, a  ``best  match''  search  is
     performed during string translation. For example, if a user  specifies
     en_UK_Funky, the locales ``en_UK_Funky'', ``en_UK'',  and  ``en''  are
     searched in order until a matching translation string is found. If  no
     translation string is available, then ::msgcat::unknown is called.


NAMESPACES AND MESSAGE CATALOGS
     Strings stored in the message  catalog  are  stored  relative  to  the
     namespace from which they were added. This allows multiple packages to
     use the same strings without fear of collisions with  other  packages.
     It also allows the source string to  be  shorter  and  less  prone  to
     typographical error.
     For example, executing  the  code  mcset  en  hello  "hello  from  ::"
     namespace eval foo {mcset en hello "hello from ::foo"} puts [mc hello]
     namespace eval foo {puts [mc hello]} will print hello  from  ::  hello
     from ::foo
     When searching for a translation of a  message,  the  message  catalog
     will search first the  current  namespace,  then  the  parent  of  the
     current namespace, and so on until the global  namespace  is  reached.
     This allows child namespaces to "inherit" messages from  their  parent
     namespace. 
     For example, executing the code mcset en m1 ":: message1" mcset en  m2
     ":: message2" mcset en m3 ":: message3" namespace eval ::foo  {  mcset
     en m2 "::foo message2" mcset en m3 "::foo message3" }  namespace  eval
     ::foo::bar { mcset en m3 "::foo::bar message3" } puts  "[mc  m1];  [mc
     m2]; [mc m3]" namespace eval ::foo {puts "[mc m1]; [mc m2]; [mc  m3]"}
     namespace eval ::foo::bar {puts "[mc m1];  [mc  m2];  [mc  m3]"}  will
     print ::  message1;  ::  message2;  ::  message3  ::  message1;  ::foo
     message2; ::foo  message3  ::  message1;  ::foo  message2;  ::foo::bar
     message3 

LOCATION AND FORMAT OF MESSAGE FILES
     Message files  can  be  located  in  any  directory,  subject  to  the
     following conditions:
          [1] 
               All message files for a package are in the same directory.
          [2] 
               The message file name is  a  locale  specifier  followed  by
               ``.msg''. For example: es.msg --  spanish  en_UK.msg  --  UK
               English 
          [3] 
               The file contains a series of calls to  mcset,  setting  the
               necessary translation strings for the language. For example:
               ::msgcat::mcset es "Free Beer!" "Cerveza Gracias!"
RECOMMENDED MESSAGE SETUP FOR PACKAGES
     If a package is installed into a subdirectory of the  tcl_pkgPath  and
     loaded via package require, the following procedure is recommended.
          [1] 
               During package  installation,  create  a  subdirectory  msgs
               under your package directory.
          [2] 
               Copy your *.msg files into that directory.
          [3] 
               Add the following command  to  your  package  initialization
               script: # load language files, stored in  msgs  subdirectory
               ::msgcat::mcload [file join  [file  dirname  [info  script]]
               msgs] 
POSTITIONAL CODES FOR FORMAT AND SCAN COMMANDS
     It is possible that a message string used as  an  argument  to  format
     might have positionally dependent parameters that  might  need  to  be
     repositioned. For example, it  might  be  syntactically  desirable  to
     rearrange the sentence structure while   translating.    format    "We
     produced %d units in location %s" $num $city format "In location %s we
     produced %d units" $city $num
     This can be handled by using the  positional  parameters:  format  "We
     produced %1\$d units in location %2\$s" $num $city format "In location
     %2\$s we produced %1\$d units" $num $city
     Similarly, positional parameters can be  used  with  scan  to  extract
     values from internationalized strings.


CREDITS 
     The message catalog code was developed by Mark Harrison.


SEE ALSO
     format, scan, namespace, package

KEYWORDS 
     internationalization, i18n, localization,   l10n,    message,    text,
     translation 





_________________________________________________________________

NAME
     namespace - create and manipulate contexts for commands and variables

SYNOPSIS
	namespace ?option? ?arg ...?

_________________________________________________________________

DESCRIPTION 
     The namespace command lets you create, access,  and  destroy  separate
     contexts for commands  and  variables.  See  the  section  WHAT  IS  A
     NAMESPACE? below  for  a  brief  overview  of  namespaces.  The  legal
     option's are listed below. Note that you can abbreviate the option's.
          namespace children ?namespace? ?pattern?
               Returns a list of all child namespaces that  belong  to  the
               namespace namespace. If namespace is not specified, then the
               children  are  returned  for  the  current  namespace.  This
               command returns fully-qualified names, which start with  ::.
               If the optional pattern is given, then this command  returns
               only the names that match the glob-style pattern. The actual
               pattern used is determined as follows: a pattern that starts
               with :: is used directly, otherwise the namespace  namespace
               (or the fully-qualified name of the  current  namespace)  is
               prepended onto the the pattern.
          namespace code script
               Captures the current namespace context for  later  execution
               of the script script. It  returns  a  new  script  in  which
               script has been wrapped in a namespace code command. The new
               script has  two  important  properties.  First,  it  can  be
               evaluated in any namespace  and  will  cause  script  to  be
               evaluated in  the  current  namespace  (the  one  where  the
               namespace code  command  was  invoked).  Second,  additional
               arguments can be appended to the resulting script  and  they
               will be  passed  to  script  as  additional  arguments.  For
               example, suppose the command set script [namespace code {foo
               bar}] is invoked in namespace ::a::b. Then eval  "$script  x
               y" can be executed in any namespace (assuming the  value  of
               script has been passed in properly) and will have  the  same
               effect as the command namespace eval ::a::b {foo bar  x  y}.
               This command is needed because extensions like  Tk  normally
               execute callback scripts in the global namespace.  A  scoped
               command captures  a  command  together  with  its  namespace
               context in a way that allows  it  to  be  executed  properly
               later. See the section SCOPED VALUES for  some  examples  of
               how this is used to create callback scripts.
          namespace current
               Returns the fully-qualified name for the current  namespace.
               The actual name of the global namespace is  ``''  (i.e.,  an
               empty string), but this command returns ::  for  the  global
               namespace as a convenience to programmers.
          namespace delete ?namespace namespace ...?
               Each namespace  namespace  is  deleted  and  all  variables,
               procedures, and child namespaces contained in the  namespace
               are deleted. If a procedure is  currently  executing  inside
               the namespace, the namespace will be kept  alive  until  the
               procedure returns;  however,  the  namespace  is  marked  to
               prevent other  code  from  looking  it  up  by  name.  If  a
               namespace doesn't exist, this command returns an  error.  If
               no namespace names are given, this command does nothing.
          namespace eval namespace arg ?arg ...?
               Activates a namespace called namespace  and  evaluates  some
               code in that context. If  the  namespace  does  not  already
               exist, it is created. If  more  than  one  arg  argument  is
               specified, the arguments are concatenated  together  with  a
               space between each one in  the  same  fashion  as  the  eval
               command, and the result is evaluated.
               If  namespace  has  leading  namespace  qualifiers  and  any
               leading namespaces do  not  exist,  they  are  automatically
               created. 
          namespace exists namespace
               Returns 1 if namespace is a valid namespace in  the  current
               context, returns 0 otherwise.
          namespace export ?-clear? ?pattern pattern ...?
               Specifies which commands are exported from a namespace.  The
               exported commands are those that can be later imported  into
               another namespace using a  namespace  import  command.  Both
               commands defined in a namespace and commands  the  namespace
               has previously imported can be exported by a namespace.  The
               commands do not have to be defined at the time the namespace
               export command is executed. Each   pattern    may    contain
               glob-style special characters, but it may  not  include  any
               namespace qualifiers. That is, the pattern can only  specify
               commands in the current (exporting) namespace. Each  pattern
               is appended onto the namespace's list of export patterns. If
               the -clear flag is given,  the  namespace's  export  pattern
               list is reset to empty  before  any  pattern  arguments  are
               appended. If no patterns are given and the -clear flag isn't
               given, this command returns the namespace's  current  export
               list. 
          namespace forget ?pattern pattern ...?
               Removes previously imported commands from a namespace.  Each
               pattern is a qualified name  such  as  foo::x  or  a::b::p*.
               Qualified names contain ::s and qualify a name with the name
               of one or more namespaces. Each pattern  is  qualified  with
               the name of an exporting namespace and may  have  glob-style
               special characters in the command name at  the  end  of  the
               qualified name. Glob characters may not    appear    in    a
               namespace  name.  This  command  first  finds  the  matching
               exported commands. It then checks whether any of those those
               commands were previously imported by the current  namespace.
               If so,  this  command  deletes  the  corresponding  imported
               commands. In effect, this un-does the action of a  namespace
               import command.
          namespace import ?-force? ?pattern pattern ...?
               Imports  commands  into  a  namespace.  Each  pattern  is  a
               qualified name like foo::x or a::p*. That  is,  it  includes
               the name of an exporting namespace and may  have  glob-style
               special characters in the command name at  the  end  of  the
               qualified name. Glob characters may not    appear    in    a
               namespace name. All the commands that match a pattern string
               and which are currently exported from  their  namespace  are
               added to the current namespace. This is done by  creating  a
               new command in the current  namespace  that  points  to  the
               exported command in its original  namespace;  when  the  new
               imported command is called, it invokes the exported command.
               This command  normally  returns  an  error  if  an  imported
               command conflicts with an existing command. However, if  the
               -force option is  given,  imported  commands  will  silently
               replace existing commands. The namespace import command  has
               snapshot semantics: that is, only  requested  commands  that
               are currently defined in the   exporting    namespace    are
               imported. In other words, you can import only  the  commands
               that are in a namespace  at  the  time  when  the  namespace
               import command is executed. If another  command  is  defined
               and exported in this namespace later  on,  it  will  not  be
               imported. 
          namespace inscope namespace arg ?arg ...?
               Executes a script in the context of a particular  namespace.
               This  command  is  not  expected  to  be  used  directly  by
               programmers; calls  to  it  are  generated  implicitly  when
               applications use namespace code commands to create  callback
               scripts that the applications then register with,  e.g.,  Tk
               widgets. The namespace inscope  command  is  much  like  the
               namespace eval command except that it has lappend  semantics
               and the namespace must already exist. It  treats  the  first
               argument as a list, and  appends  any  arguments  after  the
               first onto  the  end  as  proper  list  elements.  namespace
               inscope ::foo a x y z is equivalent to namespace eval  ::foo
               [concat a [list x y z]] This lappend semantics is  important
               because many callback scripts are actually prefixes.
          namespace origin command
               Returns the fully-qualified name of the original command  to
               which the imported command command refers. When a command is
               imported into a namespace, a new command is created in  that
               namespace that points to the actual command in the exporting
               namespace. If a command  is  imported  into  a  sequence  of
               namespaces a, b,...,n where each successive  namespace  just
               imports  the  command  from  the  previous  namespace,  this
               command returns the fully-qualified  name  of  the  original
               command in the first namespace, a. If command does not refer
               to an imported command, the  command's  own  fully-qualified
               name is returned.
          namespace parent ?namespace?
               Returns the fully-qualified name of the parent namespace for
               namespace namespace. If  namespace  is  not  specified,  the
               fully-qualified name of the current  namespace's  parent  is
               returned. 
          namespace qualifiers string
               Returns any leading namespace   qualifiers    for    string.
               Qualifiers are namespace names separated  by  ::s.  For  the
               string ::foo::bar::x, this command returns  ::foo::bar,  and
               for :: it returns an  empty  string.  This  command  is  the
               complement of the namespace tail command. Note that it  does
               not check whether the namespace  names  are,  in  fact,  the
               names of currently defined namespaces.
          namespace tail string
               Returns the simple name at the end of  a  qualified  string.
               Qualifiers are namespace names separated  by  ::s.  For  the
               string ::foo::bar::x, this command returns x, and for ::  it
               returns an empty string. This command is the  complement  of
               the namespace qualifiers command. It does not check  whether
               the namespace names are, in fact,  the  names  of  currently
               defined namespaces.
          namespace which ?-command? ?-variable? name
               Looks up name as either a command or  variable  and  returns
               its fully-qualified name. For  example,  if  name  does  not
               exist in the current namespace but does exist in the  global
               namespace, this command returns a  fully-qualified  name  in
               the global namespace. If the command or  variable  does  not
               exist, this command returns an empty string. If the variable
               has been created but not defined, such as with the  variable
               command or through a trace on  the  variable,  this  command
               will return the fully-qualified name of the variable. If  no
               flag is given, name is treated as a command  name.  See  the
               section NAME RESOLUTION below  for  an  explanation  of  the
               rules regarding name resolution.

WHAT IS A NAMESPACE?
     A namespace is a collection of commands and variables. It encapsulates
     the commands and variables to ensure that they  won't  interfere  with
     the commands and variables of other namespaces. Tcl has always had one
     such collection, which we refer to as the global namespace. The global
     namespace holds all global variables and commands. The namespace  eval
     command lets you create new namespaces. For  example,  namespace  eval
     Counter { namespace export bump variable num 0

    proc bump {} {
        variable num
        incr num
    }
}
creates a new namespace containing the variable num and
the procedure bump.
The commands and variables in this namespace are separate from
other commands and variables in the same program.
If there is a command named bump in the global namespace,
for example, it will be different from the command bump
in the Counter namespace.
     Namespace variables resemble  global  variables  in  Tcl.  They  exist
     outside of the procedures in a namespace but  can  be  accessed  in  a
     procedure via the variable command, as shown in the example above.
     Namespaces are dynamic. You can add and delete commands and  variables
     at any time, so you can build up the contents of a namespace over time
     using a series of namespace eval commands. For example, the  following
     series of commands has the same effect  as  the  namespace  definition
     shown above: namespace eval Counter { variable num 0 proc  bump  {}  {
     variable num return [incr num] } } namespace eval Counter { proc  test
     {args} { return $args } } namespace eval Counter { rename  test  ""  }
     Note that the test procedure is added to the  Counter  namespace,  and
     later removed via the rename command.
     Namespaces can  have  other  namespaces  within  them,  so  they  nest
     hierarchically. A nested namespace is encapsulated inside  its  parent
     namespace and can not interfere with other namespaces.


QUALIFIED NAMES
     Each namespace has a textual name such as history  or  ::safe::interp.
     Since namespaces may nest,  qualified  names  are  used  to  refer  to
     commands, variables, and child namespaces contained inside namespaces.
     Qualified names are similar to the hierarchical path  names  for  Unix
     files or Tk widgets, except that :: is used as the  separator  instead
     of / or .. The topmost or global namespace has the name ``'' (i.e., an
     empty string), although :: is a  synonym.  As  an  example,  the  name
     ::safe::interp::create refers to the command create in  the  namespace
     interp that is a child of of namespace ::safe,  which  in  turn  is  a
     child of the global namespace ::.
     If you want to access commands and variables from  another  namespace,
     you must use some  extra  syntax.  Names  must  be  qualified  by  the
     namespace that contains them. From  the  global  namespace,  we  might
     access the Counter   procedures    like    this:    Counter::bump    5
     Counter::Reset We could access  the  current  count  like  this:  puts
     "count = $Counter::num" When one namespace contains another,  you  may
     need more than one qualifier to  reach  its  elements.  If  we  had  a
     namespace Foo that contained the namespace Counter, you  could  invoke
     its bump procedure from    the    global    namespace    like    this:
     Foo::Counter::bump 3
     You can also use qualified names when you create and rename  commands.
     For example, you could add a procedure to the Foo namespace like this:
     proc Foo::Test {args} {return $args}  And  you  could  move  the  same
     procedure to another namespace like this: rename Foo::Test Bar::Test
     There are a few remaining points about qualified names that we  should
     cover. Namespaces have nonempty names except for the global namespace.
     :: is disallowed in simple  command,  variable,  and  namespace  names
     except as a namespace separator. Extra :s  in  a  qualified  name  are
     ignored; that is, two or more :s are treated as a namespace separator.
     A trailing :: in a qualified variable or command name  refers  to  the
     variable or command named {}. However, a trailing ::  in  a  qualified
     namespace name is ignored.


NAME RESOLUTION
     In general, all Tcl commands that  take  variable  and  command  names
     support qualified names. This means you can give  qualified  names  to
     such commands as set, proc, rename, and interp alias. If you provide a
     fully-qualified name that starts with a ::, there is no question about
     what command, variable, or namespace you mean. However,  if  the  name
     does not start with a :: (i.e., is relative), Tcl follows a fixed rule
     for looking it up: Command and variable names are always  resolved  by
     looking first in  the  current  namespace,  and  then  in  the  global
     namespace. Namespace names, on the other hand, are always resolved  by
     looking in only the current namespace.
     In the following example, set traceLevel  0  namespace  eval  Debug  {
     printTrace $traceLevel } Tcl looks for  traceLevel  in  the  namespace
     Debug and then in the  global  namespace.  It  looks  up  the  command
     printTrace in the same way. If a variable or command name is not found
     in  either  context,  the  name  is  undefined.  To  make  this  point
     absolutely clear, consider the following  example:  set  traceLevel  0
     namespace eval Foo { variable traceLevel 3

    namespace eval Debug {
        printTrace $traceLevel
    }
}
Here Tcl looks for traceLevel first in the namespace Foo::Debug.
Since it is not found there, Tcl then looks for it 
in the global namespace.
The variable Foo::traceLevel is completely ignored
during the name resolution process.
     You can use the namespace which  command  to  clear  up  any  question
     about name  resolution.  For  example,  the  command:  namespace  eval
     Foo::Debug  {namespace    which    -variable    traceLevel}    returns
     ::traceLevel. On the other  hand,  the  command,  namespace  eval  Foo
     {namespace which -variable traceLevel} returns ::Foo::traceLevel.
     As mentioned above, namespace names are  looked  up  differently  than
     the names of  variables  and  commands.  Namespace  names  are  always
     resolved in the current namespace. This means,  for  example,  that  a
     namespace eval command that creates a new namespace always  creates  a
     child of the current namespace unless the new  namespace  name  begins
     with a ::.
     Tcl has no access  control  to  limit  what  variables,  commands,  or
     namespaces you can reference. If you provide  a  qualified  name  that
     resolves to an element by the name  resolution  rule  above,  you  can
     access the element.
     You can access a namespace variable  from  a  procedure  in  the  same
     namespace by using the variable command. Much like the global command,
     this creates a local link to the namespace variable. If necessary,  it
     also creates the variable in the current namespace and initializes it.
     Note that the global command only creates links to  variables  in  the
     global namespace. It is not necessary to use a variable command if you
     always refer to the namespace variable using an appropriate  qualified
     name. 


IMPORTING COMMANDS
     Namespaces  are  often  used  to  represent  libraries.  Some  library
     commands are used so frequently that it is a nuisance  to  type  their
     qualified names. For example, suppose that all of the  commands  in  a
     package like BLT are contained in a namespace  called  Blt.  Then  you
     might access these commands like this: Blt::graph .g  -background  red
     Blt::table  .  .g  0,0  If  you  use  the  graph  and  table  commands
     frequently, you may want to access them without the Blt:: prefix.  You
     can do this by importing the commands into the current namespace, like
     this: namespace import Blt::* This adds all exported commands from the
     Blt namespace into the current namespace context,  so  you  can  write
     code like this: graph .g -background red table . .g 0,0 The  namespace
     import command only  imports  commands  from  a  namespace  that  that
     namespace exported with a namespace export command.
     Importing every command from a  namespace  is  generally  a  bad  idea
     since you don't know what you will get. It is better  to  import  just
     the specific commands you need. For  example,  the  command  namespace
     import Blt::graph Blt::table imports only the graph and table commands
     into the current context.
     If you try to import a command that already exists, you  will  get  an
     error. This prevents you from importing  the  same  command  from  two
     different packages. But from time to time  (perhaps  when  debugging),
     you may want to get around this restriction. You may want  to  reissue
     the namespace import  command  to  pick  up  new  commands  that  have
     appeared in a namespace. In that case, you can use the -force  option,
     and existing commands will be silently overwritten:  namespace  import
     -force Blt::graph Blt::table If for some  reason,  you  want  to  stop
     using the imported commands, you can remove  them  with  an  namespace
     forget command, like this: namespace forget Blt::* This  searches  the
     current namespace for any commands imported from Blt. If it finds any,
     it removes them. Otherwise, it  does  nothing.  After  this,  the  Blt
     commands must be accessed with the Blt:: prefix.
     When you delete a command from  the  exporting  namespace  like  this:
     rename Blt::graph "" the command is  automatically  removed  from  all
     namespaces that import it.


EXPORTING COMMANDS
     You can export commands from a namespace  like  this:  namespace  eval
     Counter { namespace export bump reset variable Num 0 variable Max 100

    proc bump {{by 1}} {
        variable Num
        incr Num $by
        Check
        return $Num
    }
    proc reset {} {
        variable Num
        set Num 0
    }
    proc Check {} {
        variable Num
        variable Max
        if {$Num > $Max} {
            error "too high!"
        }
    }
}
The procedures bump and reset are exported,
so they are included when you import from the Counter namespace,
like this:
namespace import Counter::*
However, the Check procedure is not exported,
so it is ignored by the import operation.
     The namespace import command only imports commands that were  declared
     as exported by their namespace. The namespace export command specifies
     what commands may be imported by  other  namespaces.  If  a  namespace
     import command specifies a command that is not exported,  the  command
     is not imported.


SEE ALSO
     variable 

KEYWORDS 
     exported, internal, variable






_________________________________________________________________

NAME
     open - Open a file-based or command pipeline channel

SYNOPSIS
	open fileName
	open fileName access
	open fileName access permissions

_________________________________________________________________

DESCRIPTION 
     This command opens a  file,  serial  port,  or  command  pipeline  and
     returns a channel identifier that may be used in future invocations of
     commands like read,  puts,  and  close.  If  the  first  character  of
     fileName is not | then the command opens a file:  fileName  gives  the
     name of the file to open, and  it  must  conform  to  the  conventions
     described in the filename manual entry.
     The access argument, if present, indicates the way in which  the  file
     (or command pipeline) is to be accessed. In the first form access  may
     have any of the following values:
          r 
               Open the file for reading only; the file must already exist.
               This is the default value if access is not specified.
          r+ 
               Open the file for both reading and writing;  the  file  must
               already exist.
          w 
               Open the file for writing only. Truncate it if it exists. If
               it doesn't exist, create a new file.
          w+ 
               Open the file for reading and writing.  Truncate  it  if  it
               exists. If it doesn't exist, create a new file.
          a 
               Open the file for writing only. If the file  doesn't  exist,
               create a new empty file. Set the initial access position  to
               the end of the file.
          a+ 
               Open the file for reading and writing. If the  file  doesn't
               exist, create a new  empty  file.  Set  the  initial  access
               position to the end of the file.
     In the second form, access consists of a list of any of the  following
     flags, all of which have the standard POSIX meanings. One of the flags
     must be either RDONLY, WRONLY or RDWR.
          RDONLY 
               Open the file for reading only.
          WRONLY 
               Open the file for writing only.
          RDWR 
               Open the file for both reading and writing.
          APPEND 
               Set the file pointer to the end of the file  prior  to  each
               write. 
          CREAT 
               Create the file if it doesn't already  exist  (without  this
               flag it is an error for the file not to exist).
          EXCL 
               If CREAT is also specified, an error is returned if the file
               already exists.
          NOCTTY 
               If the file is a terminal device,  this  flag  prevents  the
               file from becoming the controlling terminal of the process.
          NONBLOCK 
               Prevents the process from blocking while opening  the  file,
               and possibly in subsequent I/O   operations.    The    exact
               behavior of this flag is system- and  device-dependent;  its
               use is discouraged (it  is  better  to  use  the  fconfigure
               command to put a file  in  nonblocking  mode).  For  details
               refer to your system documentation on the open system call's
               O_NONBLOCK flag.
          TRUNC 
               If the file exists it is truncated to zero length.
     If a new file is created  as  part  of  opening  it,  permissions  (an
     integer)  is  used  to  set  the  permissions  for  the  new  file  in
     conjunction with the process's file mode  creation  mask.  Permissions
     defaults to 0666.

COMMAND PIPELINES
     If the first  character  of  fileName  is  ``|''  then  the  remaining
     characters of fileName  are  treated  as  a  list  of  arguments  that
     describe a command pipeline to  invoke,  in  the  same  style  as  the
     arguments for exec. In this case, the channel identifier  returned  by
     open may be used to write to the command's input pipe or read from its
     output pipe, depending on the value of access. If write-only access is
     used (e.g. access is w), then standard  output  for  the  pipeline  is
     directed to the current  standard  output  unless  overridden  by  the
     command. If read-only access is used  (e.g.  access  is  r),  standard
     input for the pipeline is taken from the current standard input unless
     overridden by the command.

SERIAL COMMUNICATIONS
     If fileName refers to a serial port, then the specified serial port is
     opened and initialized  in  a  platform-dependent  manner.  Acceptable
     values for the fileName to use to open a serial port are described  in
     the PORTABILITY ISSUES section.


CONFIGURATION OPTIONS
     The fconfigure command can be used to  query  and  set  the  following
     configuration option for open serial ports:
          -mode baud,parity,data,stop
               This option is a set of 4 comma-separated values:  the  baud
               rate, parity, number of data bits, and number of  stop  bits
               for this serial port. The baud rate is a simple integer that
               specifies  the  connection  speed.  Parity  is  one  of  the
               following letters: n, o, e, m,  s;  respectively  signifying
               the parity options of ``none'', ``odd'', ``even'', ``mark'',
               or ``space''. Data is the number of data bits and should  be
               an integer from 5 to 8, while stop is  the  number  of  stop
               bits and should be the integer 1 or 2.
          -pollinterval msec
               This option, available only on Windows for serial ports,  is
               used to set the maximum time between polling for fileevents.
               This affects the time interval between checking  for  events
               throughout the Tcl interpreter (the  smallest  value  always
               wins). Use this option only if you want to poll  the  serial
               port more often than 10 msec (the default).
          -lasterror 
               This option is available only on Windows for  serial  ports,
               and is query only  (will  only  be  reported  when  directly
               requested). In case of a serial communication error, read or
               puts returns  a  general  Tcl  file  I/O  error.  fconfigure
               -lasterror can be called to get  a  list  of  error  details
               (e.g. FRAME RXOVER).

PORTABILITY ISSUES
          Windows (all versions)
               Valid values for fileName to open a serial port are  of  the
               form comX:, where X is a number, generally from 1 to 4. This
               notation only works for serial ports from 1  to  9,  if  the
               system happens to have more than four. An attempt to open  a
               serial port that does not exist or has a number greater than
               9 will fail. An alternate form of opening serial ports is to
               use the filename  \\.\comX,  where  X  is  any  number  that
               corresponds to a serial port; please note that  this  method
               is considerably slower on Windows 95 and Windows 98.
          Windows NT
               When running Tcl interactively, there may  be  some  strange
               interactions between the real console, if  one  is  present,
               and a command pipeline that uses standard input  or  output.
               If a command pipeline is opened for  reading,  some  of  the
               lines entered at the console will be  sent  to  the  command
               pipeline and some will be sent to the Tcl  evaluator.  If  a
               command pipeline is opened for writing,  keystrokes  entered
               into the console are not  visible  until  the  the  pipe  is
               closed. This behavior occurs whether the command pipeline is
               executing 16-bit or 32-bit applications. These problems only
               occur  because  both  Tcl  and  the  child  application  are
               competing for the console at the same time. If  the  command
               pipeline is started from  a  script,  so  that  Tcl  is  not
               accessing the console, or if the command pipeline  does  not
               use standard input or output, but is redirected from or to a
               file, then the above problems do not occur.
          Windows 95
               A command pipeline that executes a  16-bit  DOS  application
               cannot be opened for both reading and writing, since  16-bit
               DOS applications that receive standard input from a pipe and
               send standard output to a pipe  run  synchronously.  Command
               pipelines that do not execute 16-bit  DOS  applications  run
               asynchronously and  can  be  opened  for  both  reading  and
               writing. 
               When running Tcl interactively, there may  be  some  strange
               interactions between the real console, if  one  is  present,
               and a command pipeline that uses standard input  or  output.
               If a command pipeline is opened for reading  from  a  32-bit
               application, some of the keystrokes entered at  the  console
               will be sent to the command pipeline and some will  be  sent
               to the Tcl evaluator. If a command pipeline  is  opened  for
               writing to a 32-bit application, no output is visible on the
               console until the the pipe is closed.  These  problems  only
               occur  because  both  Tcl  and  the  child  application  are
               competing for the console at the same time. If  the  command
               pipeline is started from  a  script,  so  that  Tcl  is  not
               accessing the console, or if the command pipeline  does  not
               use standard input or output, but is redirected from or to a
               file, then the above problems do not occur.
               Whether or not Tcl is running interactively,  if  a  command
               pipeline is opened for reading    from    a    16-bit    DOS
               application, the call to open will    not    return    until
               end-of-file has been received from  the  command  pipeline's
               standard output. If a command pipeline is opened for writing
               to a 16-bit DOS application, no data will  be  sent  to  the
               command pipeline's standard output until   the    pipe    is
               actually closed. This  problem  occurs  because  16-bit  DOS
               applications are run synchronously, as described above.
          Macintosh 
               Opening a serial port is  not  currently  implemented  under
               Macintosh. 
               Opening a command pipeline   is    not    supported    under
               Macintosh, since applications do not support the concept  of
               standard input or output.
          Unix 
               Valid  values  for  fileName  to  open  a  serial  port  are
               generally of the form /dev/ttyX, where X is a or b, but  the
               name of any pseudo-file that maps to a serial  port  may  be
               used. 
               When running Tcl interactively, there may  be  some  strange
               interactions between the console, if one is present,  and  a
               command pipeline that uses  standard  input.  If  a  command
               pipeline is opened for reading, some of the lines entered at
               the console will be sent to the command  pipeline  and  some
               will be sent to the Tcl evaluator. This problem only  occurs
               because both Tcl and the child application are competing for
               the console at the same time. If  the  command  pipeline  is
               started from a script, so that  Tcl  is  not  accessing  the
               console, or if the command pipeline does  not  use  standard
               input, but is redirected from a file, then the above problem
               does not occur.
     See the PORTABILITY ISSUES section of the exec command for  additional
     information not specific to command    pipelines    about    executing
     applications on the various platforms


SEE ALSO
     file, close, filename, gets, read, puts, exec, fopen

KEYWORDS 
     access mode, append, create, file,  non-blocking,  open,  permissions,
     pipeline, process, serial






_________________________________________________________________

NAME
     package - Facilities for package loading and version control

SYNOPSIS
	package forget ?package package ...?
	package ifneeded package version ?script?
	package names
	package present ?-exact? package ?version?
	package provide package ?version?
	package require ?-exact? package ?version?
	package unknown ?command?
	package vcompare version1 version2
	package versions package
	package vsatisfies version1 version2

_________________________________________________________________

DESCRIPTION 
     This command keeps a simple database of the packages available for use
     by the current interpreter and how to load them into the  interpreter.
     It supports multiple versions of each package  and  arranges  for  the
     correct version of a package to be loaded based on what is  needed  by
     the  application.  This  command  also  detects  and  reports  version
     clashes. Typically, only  the  package  require  and  package  provide
     commands are invoked in normal Tcl scripts;  the  other  commands  are
     used primarily by system scripts that maintain the package database.
     The behavior of  the  package  command  is  determined  by  its  first
     argument. The following forms are permitted:
          package forget ?package package ...?
               Removes all information about each  specified  package  from
               this interpreter, including  information  provided  by  both
               package ifneeded and package provide.
          package ifneeded package version ?script?
               This command typically appears only in system  configuration
               scripts to set up the package database. It indicates that  a
               particular version of a particular package is  available  if
               needed, and that the package can be added to the interpreter
               by executing script. The script is saved in a  database  for
               use  by  subsequent  package  require  commands;  typically,
               script sets up auto-loading for the commands in the  package
               (or calls load and/or source directly), then invokes package
               provide to indicate that the package is present.  There  may
               be information in the database   for    several    different
               versions of  a  single  package.  If  the  database  already
               contains information for package and version, the new script
               replaces  the  existing  one.  If  the  script  argument  is
               omitted, the current script for version version  of  package
               package is returned,  or  an  empty  string  if  no  package
               ifneeded command has  been  invoked  for  this  package  and
               version. 
          package names
               Returns  a  list  of  the  names  of  all  packages  in  the
               interpreter for which  a  version  has  been  provided  (via
               package provide) or for which a package ifneeded  script  is
               available. The order of elements in the list is arbitrary.
          package present ?-exact? package ?version?
               This command is equivalent to package require except that it
               does not try and load the  package  if  it  is  not  already
               loaded. 
          package provide package ?version?
               This command is invoked to indicate that version version  of
               package package is now present in  the  interpreter.  It  is
               typically invoked once as part of an  ifneeded  script,  and
               again by the package itself when it is  finally  loaded.  An
               error occurs if a different  version  of  package  has  been
               provided by a  previous  package  provide  command.  If  the
               version argument is omitted, then the  command  returns  the
               version number that  is  currently  provided,  or  an  empty
               string if no package provide command has  been  invoked  for
               package in this interpreter.
          package require ?-exact? package ?version?
               This command is typically invoked by Tcl code that wishes to
               use a  particular  version  of  a  particular  package.  The
               arguments indicate which package is wanted, and the  command
               ensures that a suitable version of  the  package  is  loaded
               into the interpreter. If the command  succeeds,  it  returns
               the version number that is loaded; otherwise it generates an
               error. If both the -exact switch and  the  version  argument
               are specified then only the given version is acceptable.  If
               -exact is omitted but version is  specified,  then  versions
               later than version are also acceptable as long as they  have
               the same major version number as version. If both -exact and
               version are omitted then  any    version    whatsoever    is
               acceptable.  If  a  version  of  package  has  already  been
               provided (by invoking the package provide command), then its
               version number must satisfy the criteria given by -exact and
               version and the command returns immediately. Otherwise,  the
               command searches the database  of  information  provided  by
               previous package ifneeded commands to see if  an  acceptable
               version of the package is available. If so, the  script  for
               the highest acceptable version number is invoked; it must do
               whatever is necessary to load the package, including calling
               package provide for the package.  If  the  package  ifneeded
               database does not  contain  an  acceptable  version  of  the
               package and a package unknown command has been specified for
               the interpreter  then  that  command  is  invoked;  when  it
               completes, Tcl checks again to see if  the  package  is  now
               provided or if there is a package ifneeded script for it. If
               all of these steps fail to provide an acceptable version  of
               the package, then the command returns an error.
          package unknown ?command?
               This command supplies a ``last resort''  command  to  invoke
               during package require if no suitable version of  a  package
               can be found  in  the  package  ifneeded  database.  If  the
               command argument is supplied, it contains the first part  of
               a command; when the command  is  invoked  during  a  package
               require command, Tcl appends two additional arguments giving
               the desired  package  name  and  version.  For  example,  if
               command is foo bar and later  the  command  package  require
               test 2.4 is invoked, then Tcl will execute the  command  foo
               bar test 2.4 to load the package. If no  version  number  is
               supplied to the package require command,  then  the  version
               argument for the invoked command will be an empty string. If
               the package unknown command is  invoked  without  a  command
               argument, then the current package   unknown    script    is
               returned, or an empty string if there is none. If command is
               specified as an  empty  string,  then  the  current  package
               unknown script is removed, if there is one.
          package vcompare version1 version2
               Compares the two  version  numbers  given  by  version1  and
               version2. Returns -1 if version1 is an earlier version  than
               version2, 0 if they are equal, and 1 if  version1  is  later
               than version2.
          package versions package
               Returns a list of all the version  numbers  of  package  for
               which information has  been  provided  by  package  ifneeded
               commands. 
          package vsatisfies version1 version2
               Returns 1 if scripts written for    version2    will    work
               unchanged with  version1  (i.e.  version1  is  equal  to  or
               greater than version2 and they  both  have  the  same  major
               version number), 0 otherwise.

VERSION NUMBERS
     Version numbers consist of one or more decimal  numbers  separated  by
     dots, such as 2 or 1.162 or 3.1.13.1. The first number is  called  the
     major version number. Larger numbers correspond to later versions of a
     package,  with  leftmost  numbers  having  greater  significance.  For
     example, version 2.1 is later than 1.3 and version 3.4.6 is later than
     3.3.5. Missing fields are equivalent to zeroes:  version  1.3  is  the
     same as version 1.3.0 and 1.3.0.0, so it  is  earlier  than  1.3.1  or
     1.3.0.2. A later version number is assumed to  be  upwards  compatible
     with an earlier version number as long as both versions have the  same
     major version number. For example, Tcl scripts written for version 2.3
     of a package should work unchanged  under  versions  2.3.2,  2.4,  and
     2.5.1. Changes  in  the  major  version  number  signify  incompatible
     changes: if code is written to use version 2.1 of a package, it is not
     guaranteed to work unmodified with either  version  1.7.3  or  version
     3.1. 


PACKAGE INDICES
     The recommended way to use  packages  in  Tcl  is  to  invoke  package
     require and package provide commands in scripts, and use the procedure
     pkg_mkIndex to create package index  files.  Once  you've  done  this,
     packages will be loaded automatically in response to  package  require
     commands. See the documentation for pkg_mkIndex for details.


SEE ALSO
     msgcat, packagens, pkgMkIndex

KEYWORDS 
     package, version





_________________________________________________________________

NAME
     pkg::create - Construct an appropriate package ifneeded command for  a
     given package specification

SYNOPSIS
	::pkg::create -name packageName -version packageVersion ?-load filespec? ... ?-source filespec? ...

_________________________________________________________________

DESCRIPTION 
     ::pkg::create is a utility procedure that is part of the standard  Tcl
     library. It is used to create an appropriate package ifneeded  command
     for a given package specification. It  can  be  used  to  construct  a
     pkgIndex.tcl file for use with the package mechanism.


OPTIONS 
     The parameters supported are:
          -name packageName
               This parameter specifies the name  of  the  package.  It  is
               required. 
          -version packageVersion
               This parameter specifies the version of the package.  It  is
               required. 
          -load filespec
               This parameter specifies  a  binary  library  that  must  be
               loaded with the load command. filespec is a  list  with  two
               elements. The first element is the name of the file to load.
               The second, optional element is a list of commands  supplied
               by loading that file. If the list of procedures is empty  or
               omitted, ::pkg::create will set up the  library  for  direct
               loading (see pkg_mkIndex). Any number  of  -load  parameters
               may be specified.
          -source filespec
               This parameter is similar to  the  -load  parameter,  except
               that it specifies a Tcl library that must be loaded with the
               source command. Any number  of  -source  parameters  may  be
               specified. 
     At least one -load or -source paramter must be given.


SEE ALSO
     package 

KEYWORDS 
     auto-load, index, package, version





_________________________________________________________________

NAME
     pid - Retrieve process id(s)

SYNOPSIS
	pid ?fileId?

_________________________________________________________________

DESCRIPTION 
     If the fileId argument is given then it should  normally  refer  to  a
     process pipeline created with the open command. In this case  the  pid
     command will return a list whose elements are the process  identifiers
     of all the processes in the pipeline, in order. The list will be empty
     if fileId refers to an open file that isn't a process pipeline. If  no
     fileId argument is given then pid returns the  process  identifier  of
     the current process. All process identifiers are returned  as  decimal
     strings. 


SEE ALSO
     exec, open

KEYWORDS 
     file, pipeline, process identifier






_________________________________________________________________

NAME
     pkg_mkIndex - Build an index for automatic loading of packages

SYNOPSIS
	pkg_mkIndex ?-lazy? ?-load pkgPat? ?-verbose? dir ?pattern pattern ...?

_________________________________________________________________

DESCRIPTION 
     Pkg_mkIndex is a utility procedure that is part of  the  standard  Tcl
     library. It is used to create index files that allow  packages  to  be
     loaded automatically when package require commands  are  executed.  To
     use pkg_mkIndex, follow these steps:
          [1] 
               Create the package(s). Each package may consist  of  one  or
               more Tcl script files or binary files. Binary files must  be
               suitable for loading with the load  command  with  a  single
               argument; for example, if the file is  test.so  it  must  be
               possible to load this file with the  command  load  test.so.
               Each script file must contain a package provide  command  to
               declare the package and version number, and each binary file
               must contain a call to Tcl_PkgProvide.
          [2] 
               Create the index by invoking pkg_mkIndex. The  dir  argument
               gives the name of a directory and each pattern argument is a
               glob-style pattern that selects script or  binary  files  in
               dir. The default    pattern    is    *.tcl    and    *.[info
               sharedlibextension]. Pkg_mkIndex will    create    a    file
               pkgIndex.tcl in dir with package information about  all  the
               files given by  the  pattern  arguments.  It  does  this  by
               loading each file into a slave interpreter and  seeing  what
               packages  and  new  commands  appear  (this  is  why  it  is
               essential to have package provide commands or Tcl_PkgProvide
               calls in the files, as  described  above).  If  you  have  a
               package split among scripts and binary files, or if you have
               dependencies among files, you may  have  to  use  the  -load
               option or adjust the order in  which  pkg_mkIndex  processes
               the files. See COMPLEX CASES below.

          [3] 
               Install  the  package  as  a  subdirectory  of  one  of  the
               directories given by   the    tcl_pkgPath    variable.    If
               $tcl_pkgPath   contains    more    than    one    directory,
               machine-dependent packages (e.g., those that contain  binary
               shared libraries) should normally  be  installed  under  the
               first  directory  and  machine-independent  packages  (e.g.,
               those that contain only Tcl  scripts)  should  be  installed
               under the second directory. The subdirectory should  include
               the package's script and/or binary  files  as  well  as  the
               pkgIndex.tcl file. As long as the package is installed as  a
               subdirectory of a directory in    $tcl_pkgPath    it    will
               automatically be found during package require  commands.  If
               you install the package anywhere else, then you must  ensure
               that the directory containing the package    is    in    the
               auto_path global variable or an  immediate  subdirectory  of
               one of the directories in auto_path.  Auto_path  contains  a
               list of directories that are   searched    by    both    the
               auto-loader and the package loader; by default  it  includes
               $tcl_pkgPath. The package loader  also  checks  all  of  the
               subdirectories of the directories in auto_path. You can  add
               a directory to auto_path explicitly in your application,  or
               you can add the directory  to  your  TCLLIBPATH  environment
               variable: if  this  environment  variable  is  present,  Tcl
               initializes auto_path from it during application startup.
          [4] 
               Once the above steps have been taken, all you need to do  to
               use a package is to invoke package require. For example,  if
               versions 2.1, 2.3, and 3.1 of package Test have been indexed
               by pkg_mkIndex, the command package require Test  will  make
               version 3.1 available and the command package require -exact
               Test 2.1 will make version 2.1 available. There may be  many
               versions  of  a  package  in  the  various  index  files  in
               auto_path, but only one will actually be loaded in  a  given
               interpreter, based on the first  call  to  package  require.
               Different versions of a package may be loaded  in  different
               interpreters. 

OPTIONS 
     The optional switches are:
          -lazy 
               The generated index will manage to delay loading the package
               until the use  of  one  of  the  commands  provided  by  the
               package, instead of  loading  it  immediately  upon  package
               require. 
          -load pkgPat
               The index process will pre-load any packages that  exist  in
               the current interpreter and  match  pkgPat  into  the  slave
               interpreter used to generate the index.  The  pattern  match
               uses string match rules. See COMPLEX CASES below.
          -verbose 
               Generate output during the indexing process. Output  is  via
               the tclLog procedure, which by default prints to stderr.
          -- 
               End of the flags, in case dir begins with a dash.

PACKAGES AND THE AUTO-LOADER
     The package management facilities   overlap    somewhat    with    the
     auto-loader, in that both arrange for files to  be  loaded  on-demand.
     However, package management is a higher-level mechanism that uses  the
     auto-loader for the last step in the loading process. It is  generally
     better to index a package with pkg_mkIndex  rather  than  auto_mkindex
     because  the  package  mechanism  provides  version  control:  several
     versions of a package can be made available in the index  files,  with
     different applications  using  different  versions  based  on  package
     require  commands.  In  contrast,  auto_mkindex  does  not  understand
     versions so it can only handle a single version of each package. It is
     probably  not  a  good  idea  to  index  a  given  package  with  both
     pkg_mkIndex and auto_mkindex.  If  you  use  pkg_mkIndex  to  index  a
     package, its commands cannot be invoked until package require has been
     used to select a version; in  contrast,    packages    indexed    with
     auto_mkindex can  be  used  immediately  since  there  is  no  version
     control. 


HOW IT WORKS
     Pkg_mkIndex depends  on  the  package  unknown  command,  the  package
     ifneeded command, and  the  auto-loader.  The  first  time  a  package
     require command is invoked, the package  unknown  script  is  invoked.
     This is set by Tcl initialization to a script that  evaluates  all  of
     the pkgIndex.tcl  files  in  the  auto_path.  The  pkgIndex.tcl  files
     contain package ifneeded commands for each version of  each  available
     package; these commands invoke package provide  commands  to  announce
     the availability of the package,   and    they    setup    auto-loader
     information to load the files of the package. If the  -lazy  flag  was
     provided when the pkgIndex.tcl was generated, a given file of a  given
     version of a given package isn't actually loaded until the first  time
     one of its commands is invoked. Thus, after invoking  package  require
     you may not see the package's commands in  the  interpreter,  but  you
     will be able to invoke the commands and they will be auto-loaded.


DIRECT LOADING
     Some packages, for instance packages which use namespaces  and  export
     commands or those which require special initialization,  might  select
     that their package files be loaded immediately  upon  package  require
     instead of delaying the actual loading to the first use of one of  the
     package's command. This  is  the  default  mode  when  generating  the
     package index. It can be overridden by specifying the -lazy argument.


COMPLEX CASES
     Most complex cases of dependencies among scripts and binary files, and
     packages being split among scripts and binary files  are  handled  OK.
     However, you may have to adjust the order in which files are processed
     by pkg_mkIndex. These issues are described in detail below.
     If each script or file contains one package,  and  packages  are  only
     contained in one file, then things are easy. You  simply  specify  all
     files to be indexed in any order with some glob patterns.
     In general, it is  OK  for  scripts  to  have  dependencies  on  other
     packages. If scripts  contain  package  require  commands,  these  are
     stubbed out in the interpreter used to process the scripts,  so  these
     do not cause problems. If scripts call into other packages  in  global
     code, these calls are handled by a stub unknown command.  However,  if
     scripts make variable  references  to  other  package's  variables  in
     global code, these will cause errors. That is also bad coding style.
     If binary files  have  dependencies  on  other  packages,  things  can
     become tricky because it is not possible to  stub  out  C-level  API's
     such as Tcl_PkgRequire API when loading a binary  file.  For  example,
     suppose the BLT package requires Tk, and expresses this with a call to
     Tcl_PkgRequire in its Blt_Init routine. To support this, you must  run
     pkg_mkIndex in an interpreter that has Tk loaded. You can achieve this
     with the -load pkgPat option. If you specify this option,  pkg_mkIndex
     will load any packages listed by info loaded  and  that  match  pkgPat
     into the interpreter used to process files. In most  cases  this  will
     satisfy the Tcl_PkgRequire calls made by binary files.
     If you are indexing two binary files and one  depends  on  the  other,
     you should specify the one that has dependencies last.  This  way  the
     one without dependencies will get loaded and  indexed,  and  then  the
     package it  provides  will  be  available  when  the  second  file  is
     processed. You may also need  to  load  the  first  package  into  the
     temporary interpreter used to create the  index  by  using  the  -load
     flag; it won't hurt to specify  package  patterns  that  are  not  yet
     loaded. 
     If you have a package that is split across scripts and a binary  file,
     then you should avoid the -load flag. The problem is that if you  load
     a package before computing the index it masks  any  other  files  that
     provide part of the same package. If you must use -load, then you must
     specify the scripts first;  otherwise  the  package  loaded  from  the
     binary file may mask the package defined by the scripts.


SEE ALSO
     package 

KEYWORDS 
     auto-load, index, package, version





_________________________________________________________________

NAME
     proc - Create a Tcl procedure

SYNOPSIS
	proc name args body

_________________________________________________________________

DESCRIPTION 
     The proc command creates a new Tcl procedure named name, replacing any
     existing command or procedure  there  may  have  been  by  that  name.
     Whenever the new command is invoked, the  contents  of  body  will  be
     executed by the Tcl interpreter. Normally, name is  unqualified  (does
     not include the names of  any  containing  namespaces),  and  the  new
     procedure is created in the current namespace. If  name  includes  any
     namespace qualifiers,  the  procedure  is  created  in  the  specified
     namespace. Args specifies the formal arguments to  the  procedure.  It
     consists of a list, possibly empty, each of whose  elements  specifies
     one argument. Each argument specifier is also a list with  either  one
     or two fields. If there is only a single field in the  specifier  then
     it is the name of the argument; if there  are  two  fields,  then  the
     first is the argument name and the second is its default value.
     When name is invoked a local variable will be created for each of  the
     formal arguments to the procedure; its value  will  be  the  value  of
     corresponding argument in  the  invoking  command  or  the  argument's
     default value. Arguments with default values need not be specified  in
     a procedure invocation. However, there must be enough actual arguments
     for all the formal arguments that don't have defaults, and there  must
     not be any extra actual arguments. There is one special case to permit
     procedures with variable numbers of  arguments.  If  the  last  formal
     argument has the name args, then a call to the procedure  may  contain
     more actual arguments than the procedure has formals.  In  this  case,
     all of the actual arguments starting at the one that would be assigned
     to args are combined into a list (as if  the  list  command  had  been
     used); this combined value is assigned to the local variable args.
     When body is being executed, variable names normally  refer  to  local
     variables, which are created automatically when referenced and deleted
     when the  procedure  returns.  One  local  variable  is  automatically
     created for each of the procedure's arguments.  Global  variables  can
     only be accessed by invoking the global command or the upvar  command.
     Namespace variables can only be  accessed  by  invoking  the  variable
     command or the upvar command.
     The proc  command  returns  an  empty  string.  When  a  procedure  is
     invoked, the procedure's return value is  the  value  specified  in  a
     return command. If the procedure doesn't execute an  explicit  return,
     then its return value is the value of the last command executed in the
     procedure's body. If an error occurs  while  executing  the  procedure
     body, then the procedure-as-a-whole will return that same error.


SEE ALSO
     info, unknown

KEYWORDS 
     argument, procedure






_________________________________________________________________

NAME
     puts - Write to a channel

SYNOPSIS
	puts ?-nonewline? ?channelId? string

_________________________________________________________________

DESCRIPTION 
     Writes the  characters  given  by  string  to  the  channel  given  by
     channelId. ChannelId must be a channel  identifier  such  as  returned
     from a previous invocation of open or socket. It must have been opened
     for output. If no channelId is specified then it defaults  to  stdout.
     Puts normally outputs a  newline  character  after  string,  but  this
     feature may be suppressed by specifying the -nonewline switch.
     Newline characters in the output are    translated    by    puts    to
     platform-specific end-of-line sequences according to the current value
     of the -translation option  for  the  channel  (for  example,  on  PCs
     newlines are  normally    replaced    with    carriage-return-linefeed
     sequences; on Macintoshes newlines are    normally    replaced    with
     carriage-returns). See the fconfigure manual entry for a discussion on
     ways in which fconfigure will alter output.
     Tcl buffers output internally, so characters  written  with  puts  may
     not appear immediately on the output file or device; Tcl will normally
     delay output until the buffer is full or the channel  is  closed.  You
     can force output to appear immediately with the flush command.
     When the output buffer fills up, the puts command will normally  block
     until all the buffered data  has  been  accepted  for  output  by  the
     operating system. If channelId is in nonblocking mode  then  the  puts
     command will not block even if the operating system cannot accept  the
     data. Instead, Tcl continues to buffer the data and writes it  in  the
     background as fast as the underlying file or device can accept it. The
     application must use the Tcl event  loop  for  nonblocking  output  to
     work; otherwise Tcl never finds out that the file or device  is  ready
     for more output data. It is possible for an arbitrarily  large  amount
     of data to be buffered for a channel in nonblocking mode, which  could
     consume a large amount of memory. To avoid wasting memory, nonblocking
     I/O should normally be  used  in  an  event-driven  fashion  with  the
     fileevent command (don't invoke puts unless  you  have  recently  been
     notified via a file event that the channel is ready  for  more  output
     data). 


SEE ALSO
     file, fileevent

KEYWORDS 
     channel, newline, output, write






_________________________________________________________________

NAME
     pwd - Return the current working directory

SYNOPSIS
	pwd

_________________________________________________________________

DESCRIPTION 
     Returns the path name of the current working directory.


SEE ALSO
     file, cd, glob, filename

KEYWORDS 
     working directory






_________________________________________________________________

NAME
     re_syntax - Syntax of Tcl regular expressions.

_________________________________________________________________

DESCRIPTION 
     A regular expression describes strings of characters. It's  a  pattern
     that matches certain strings and doesn't match others.


DIFFERENT FLAVORS OF REs
     Regular expressions (``RE''s),  as  defined  by  POSIX,  come  in  two
     flavors: extended REs (``EREs'') and basic REs  (``BREs'').  EREs  are
     roughly those of the traditional egrep, while BREs are  roughly  those
     of the traditional  ed.  This  implementation  adds  a  third  flavor,
     advanced REs (``AREs''), basically EREs    with    some    significant
     extensions. 
     This manual page primarily  describes  AREs.  BREs  mostly  exist  for
     backward compatibility in some old programs; they will be discussed at
     the end. POSIX EREs are almost an exact subset of  AREs.  Features  of
     AREs that are not present in EREs will be indicated.


REGULAR EXPRESSION SYNTAX
     Tcl regular expressions are implemented using the package  written  by
     Henry Spencer, based on the 1003.2 spec and some (not  quite  all)  of
     the Perl5 extensions (thanks, Henry!).  Much  of  the  description  of
     regular expressions below is copied verbatim from his manual entry.
     An ARE is one or more branches, separated by  `|',  matching  anything
     that matches any of the branches.
     A branch is zero or  more    constraints    or    quantified    atoms,
     concatenated. It matches a match for the first, followed  by  a  match
     for the second, etc; an empty branch matches the empty string.
     A quantified atom is an atom possibly    followed    by    a    single
     quantifier. Without a quantifier, it matches a match for the atom. The
     quantifiers, and what a so-quantified atom matches, are:
          * 
               a sequence of 0 or more matches of the atom
          + 
               a sequence of 1 or more matches of the atom
          ? 
               a sequence of 0 or 1 matches of the atom
          {m} 
               a sequence of exactly m matches of the atom
          {m,} 
               a sequence of m or more matches of the atom
          {m,n} 
               a sequence of m through n (inclusive) matches of the atom; m
               may not exceed n
          *? +? ?? {m}? {m,}? {m,n}?
               non-greedy quantifiers, which match the same  possibilities,
               but prefer the  smallest  number  rather  than  the  largest
               number of matches (see MATCHING)
     The forms using { and } are known as bounds. The numbers m and  n  are
     unsigned decimal integers  with  permissible  values  from  0  to  255
     inclusive. 
     An atom is one of:
          (re) 
               (where re is any regular expression) matches a match for re,
               with the match noted for possible reporting
          (?:re) 
               as previous, but does no reporting (a ``non-capturing''  set
               of parentheses)
          () 
               matches an empty string, noted for possible reporting
          (?:) 
               matches an empty string, without reporting
          [chars] 
               a bracket expression, matching any one  of  the  chars  (see
               BRACKET EXPRESSIONS for more detail)
          . 
               matches any single character
          \k 
               (where k  is  a  non-alphanumeric  character)  matches  that
               character taken as an ordinary character, e.g. \\ matches  a
               backslash character
          \c 
               where c is alphanumeric (possibly    followed    by    other
               characters), an escape (AREs only), see ESCAPES below
          { 
               when followed by a character other than a digit, matches the
               left-brace character `{'; when followed by a  digit,  it  is
               the beginning of a bound (see above)
          x 
               where x is a single character with  no  other  significance,
               matches that character.
     A constraint matches an empty  string  when  specific  conditions  are
     met. A constraint may not be followed  by  a  quantifier.  The  simple
     constraints are as follows; some more constraints are described later,
     under ESCAPES.
          ^ 
               matches at the beginning of a line
          $ 
               matches at the end of a line
          (?=re) 
               positive lookahead (AREs only), matches at any point where a
               substring matching re begins
          (?!re) 
               negative lookahead (AREs only), matches at any  point  where
               no substring matching re begins
     The  lookahead  constraints  may  not  contain  back  references  (see
     later), and all parentheses within them are considered non-capturing.
     An RE may not end with `\'.


BRACKET EXPRESSIONS
     A bracket expression is a list of  characters  enclosed  in  `[]'.  It
     normally matches any single character from the list (but  see  below).
     If the list begins with `^', it matches any single character (but  see
     below) not from the rest of the list.
     If two characters in the list are separated by `-', this is  shorthand
     for the full range of characters between those two (inclusive) in  the
     collating sequence, e.g. [0-9] in ASCII matches any decimal digit. Two
     ranges may not share an endpoint, so e.g. a-c-e is illegal. Ranges are
     very collating-sequence-dependent, and portable programs should  avoid
     relying on them.
     To include a literal ] or - in the list, the  simplest  method  is  to
     enclose it in [. and .] to make it a collating  element  (see  below).
     Alternatively, make it the first character (following a possible `^'),
     or (AREs only) precede it with `\'. Alternatively, for  `-',  make  it
     the last character, or the second  endpoint  of  a  range.  To  use  a
     literal - as the first endpoint  of  a  range,  make  it  a  collating
     element or (AREs only) precede it with  `\'.  With  the  exception  of
     these, some combinations using [ (see next paragraphs),  and  escapes,
     all other special characters lose their special significance within  a
     bracket expression.
     Within a bracket expression,  a  collating  element  (a  character,  a
     multi-character  sequence  that  collates  as  if  it  were  a  single
     character, or a collating-sequence name for either) enclosed in [. and
     .] stands for the sequence of characters of  that  collating  element.
     The sequence is a single element of the bracket expression's  list.  A
     bracket expression in a  locale  that  has  multi-character  collating
     elements can thus match more than one character. So  (insidiously),  a
     bracket expression  that  starts  with  ^  can  match  multi-character
     collating elements  even  if  none  of  them  appear  in  the  bracket
     expression! (Note: Tcl  currently  has  no  multi-character  collating
     elements. This information is only for illustration.)
     For example, assume the   collating    sequence    includes    a    ch
     multi-character collating element. Then the  RE  [[.ch.]]*c  (zero  or
     more ch's  followed  by  c)  matches  the  first  five  characters  of
     `chchcc'. Also, the RE  [^c]b  matches  all  of  `chb'  (because  [^c]
     matches the multi-character ch).
     Within a bracket expression, a collating element enclosed  in  [=  and
     =] is an equivalence class, standing for the sequences  of  characters
     of all collating elements equivalent to that  one,  including  itself.
     (If there are no other equivalent collating elements, the treatment is
     as if the enclosing delimiters were `[.' and `.]'.) For example, if  o
     and &ocirc; are the members of an equivalence class,  then  `[[=o=]]',
     `[[=&ocirc;=]]', and `[o&ocirc;]' are all synonymous.  An  equivalence
     class may not  be  an  endpoint  of  a  range.  (Note:  Tcl  currently
     implements only the Unicode locale. It doesn't define any  equivalence
     classes. The examples above are just illustrations.)
     Within a bracket expression, the name of a  character  class  enclosed
     in [: and :] stands for the list of all characters (not all  collating
     elements!) belonging to that class. Standard character classes are:
               alpha A letter. upper An upper-case    letter.    lower    A
               lower-case letter. digit A  decimal    digit.    xdigit    A
               hexadecimal digit. alnum An alphanumeric (letter or  digit).
               print An alphanumeric (same as alnum). blank A space or  tab
               character.  space  A  character  producing  white  space  in
               displayed text.  punct  A  punctuation  character.  graph  A
               character with a visible  representation.  cntrl  A  control
               character. 

     A locale may provide others.    (Note    that    the    current    Tcl
     implementation has only one locale: the Unicode locale.)  A  character
     class may not be used as an endpoint of a range.
     There are two  special  cases  of  bracket  expressions:  the  bracket
     expressions  [[:<:]]  and  [[:>:]]  are  constraints,  matching  empty
     strings at the beginning and end of a word  respectively.  A  word  is
     defined as a sequence of word characters that is neither preceded  nor
     followed by word characters. A word character is an alnum character or
     an underscore (_). These special bracket expressions  are  deprecated;
     users of AREs should use constraint escapes instead (see below).

ESCAPES 
     Escapes (AREs only), which begin with a \ followed by an  alphanumeric
     character, come in several  varieties:    character    entry,    class
     shorthands, constraint escapes, and back references. A \  followed  by
     an alphanumeric character but  not  constituting  a  valid  escape  is
     illegal in AREs. In EREs, there are  no  escapes:  outside  a  bracket
     expression, a \ followed by an alphanumeric  character  merely  stands
     for that character as an ordinary  character,  and  inside  a  bracket
     expression, \ is an ordinary character. (The latter is the one  actual
     incompatibility between EREs and AREs.)
     Character-entry escapes  (AREs  only)  exist  to  make  it  easier  to
     specify non-printing and otherwise inconvenient characters in REs:
          \a 
               alert (bell) character, as in C
          \b 
               backspace, as in C
          \B 
               synonym for \ to help  reduce  backslash  doubling  in  some
               applications where there are multiple  levels  of  backslash
               processing 
          \cX 
               (where X is any character) the character whose  low-order  5
               bits are the same as those of X, and whose  other  bits  are
               all zero
          \e 
               the character whose collating-sequence  name  is  `ESC',  or
               failing that, the character with octal value 033
          \f 
               formfeed, as in C
          \n 
               newline, as in C
          \r 
               carriage return, as in C
          \t 
               horizontal tab, as in C
          \uwxyz 
               (where wxyz is exactly four hexadecimal digits) the  Unicode
               character U+wxyz in the local byte ordering
          \Ustuvwxyz 
               (where stuvwxyz is exactly   eight    hexadecimal    digits)
               reserved for a somewhat-hypothetical Unicode extension to 32
               bits 
          \v 
               vertical tab, as in C are all available.
          \xhhh 
               (where hhh  is  any  sequence  of  hexadecimal  digits)  the
               character whose hexadecimal value is   0xhhh    (a    single
               character no matter how many hexadecimal digits are used).
          \0 
               the character whose value is 0
          \xy 
               (where xy is exactly two octal digits, and  is  not  a  back
               reference (see below)) the character whose  octal  value  is
               0xy 
          \xyz 
               (where xyz is exactly three octal digits, and is not a  back
               reference (see below)) the character whose  octal  value  is
               0xyz 
     Hexadecimal digits are `0'-`9', `a'-`f',  and  `A'-`F'.  Octal  digits
     are `0'-`7'.
     The character-entry escapes are always taken as  ordinary  characters.
     For example, \135 is ] in ASCII, but \135 does not terminate a bracket
     expression. Beware, however, that  some    applications    (e.g.,    C
     compilers) interpret  such    sequences    themselves    before    the
     regular-expression  package  gets  to  see  them,  which  may  require
     doubling (quadrupling, etc.) the `\'.
     Class-shorthand escapes (AREs only)  provide  shorthands  for  certain
     commonly-used character classes:
          \d 
               [[:digit:]] 
          \s 
               [[:space:]] 
          \w 
               [[:alnum:]_] (note underscore)
          \D 
               [^[:digit:]] 
          \S 
               [^[:space:]] 
          \W 
               [^[:alnum:]_] (note underscore)
     Within bracket expressions, `\d', `\s',  and  `\w'  lose  their  outer
     brackets, and `\D', `\S', and `\W'  are  illegal.  (So,  for  example,
     [a-c\d] is equivalent  to  [a-c[:digit:]].  Also,  [a-c\D],  which  is
     equivalent to [a-c^[:digit:]], is illegal.)
     A constraint escape (AREs only) is a constraint,  matching  the  empty
     string if specific conditions are met, written as an escape:
          \A 
               matches only at the beginning of the string  (see  MATCHING,
               below, for how this differs from `^')
          \m 
               matches only at the beginning of a word
          \M 
               matches only at the end of a word
          \y 
               matches only at the beginning or end of a word
          \Y 
               matches only at a point that is not the beginning or end  of
               a word
          \Z 
               matches only at the end of the string (see MATCHING,  below,
               for how this differs from `$')
          \m 
               (where m is a nonzero digit) a back reference, see below
          \mnn 
               (where m is a nonzero digit, and nn is some more digits, and
               the decimal value mnn is not  greater  than  the  number  of
               closing capturing parentheses seen so far) a back reference,
               see below
     A word is defined as in  the  specification  of  [[:<:]]  and  [[:>:]]
     above. Constraint escapes are illegal within bracket expressions.
     A back reference (AREs only) matches the same string  matched  by  the
     parenthesized subexpression specified by the number,  so  that  (e.g.)
     ([bc])\1 matches bb  or  cc  but  not  `bc'.  The  subexpression  must
     entirely precede the back reference  in  the  RE.  Subexpressions  are
     numbered in the order  of  their  leading  parentheses.  Non-capturing
     parentheses do not define subexpressions.
     There is an    inherent    historical    ambiguity    between    octal
     character-entry escapes and back  references,  which  is  resolved  by
     heuristics, as hinted at above. A leading  zero  always  indicates  an
     octal escape. A single non-zero digit, not followed by another  digit,
     is always taken as  a  back  reference.  A  multi-digit  sequence  not
     starting with a zero is taken as a back reference if it comes after  a
     suitable subexpression (i.e. the number is in the legal  range  for  a
     back reference), and otherwise is taken as octal.

METASYNTAX 
     In addition to the main syntax described above, there are some special
     forms and miscellaneous syntactic facilities available.
     Normally the flavor of    RE    being    used    is    specified    by
     application-dependent means. However, this  can  be  overridden  by  a
     director. If an RE of any flavor begins with `***:', the rest  of  the
     RE is an ARE. If an RE of any flavor begins with `***=', the  rest  of
     the RE is taken to be a literal string, with all characters considered
     ordinary characters.
     An ARE may begin with embedded options: a sequence (?xyz)  (where  xyz
     is one or more alphabetic characters) specifies options affecting  the
     rest of the RE.  These  supplement,  and  can  override,  any  options
     specified by the application. The available option letters are:
          b 
               rest of RE is a BRE
          c 
               case-sensitive matching (usual default)
          e 
               rest of RE is an ERE
          i 
               case-insensitive matching (see MATCHING, below)
          m 
               historical synonym for n
          n 
               newline-sensitive matching (see MATCHING, below)
          p 
               partial newline-sensitive matching (see MATCHING, below)
          q 
               rest of RE is a literal (``quoted'')  string,  all  ordinary
               characters 
          s 
               non-newline-sensitive matching (usual default)
          t 
               tight syntax (usual default; see below)
          w 
               inverse partial newline-sensitive (``weird'') matching  (see
               MATCHING, below)
          x 
               expanded syntax (see below)
     Embedded options take effect at the ) terminating the  sequence.  They
     are available only at the start of an ARE, and may not be  used  later
     within it.
     In addition to the usual (tight) RE syntax, in  which  all  characters
     are significant, there is an expanded syntax, available in all flavors
     of RE with the -expanded switch,  or  in  AREs  with  the  embedded  x
     option. In the expanded syntax, white-space characters are ignored and
     all characters between a # and the following newline (or  the  end  of
     the RE) are ignored, permitting paragraphing and commenting a  complex
     RE. There are three exceptions to that basic rule:
               a white-space character or `#' preceded by `\' is retained
               white space or `#' within a bracket expression is retained
               white space and comments are illegal within  multi-character
               symbols like the ARE `(?:' or the BRE `\('

     Expanded-syntax white-space characters are blank,  tab,  newline,  and
     any character that belongs to the space character class.
     Finally, in an ARE, outside bracket    expressions,    the    sequence
     `(?#ttt)' (where ttt is any text not containing a `)') is  a  comment,
     completely ignored. Again, this is not allowed between the  characters
     of multi-character symbols  like  `(?:'.  Such  comments  are  more  a
     historical artifact than a useful facility,  and    their    use    is
     deprecated; use the expanded syntax instead.
     None of these metasyntax extensions is available  if  the  application
     (or an initial ***= director) has specified that the user's  input  be
     treated as a literal string rather than as an RE.

MATCHING 
     In the event that an RE could match more than one substring of a given
     string, the RE matches the one starting earliest in the string. If the
     RE could match more than one substring starting  at  that  point,  its
     choice is determined by its preference: either the longest  substring,
     or the shortest.
     Most atoms, and all constraints, have no preference.  A  parenthesized
     RE has the same preference (possibly none) as  the  RE.  A  quantified
     atom with quantifier {m} or {m}? has  the  same  preference  (possibly
     none) as  the  atom  itself.  A  quantified  atom  with  other  normal
     quantifiers (including {m,n} with m equal to n) prefers longest match.
     A quantified atom with other non-greedy quantifiers (including  {m,n}?
     with m equal to n) prefers shortest  match.  A  branch  has  the  same
     preference as the first quantified atom in it which has a  preference.
     An RE consisting of two or more branches connected by the  |  operator
     prefers longest match.
     Subject to the constraints imposed  by  the  rules  for  matching  the
     whole RE, subexpressions also match the longest or  shortest  possible
     substrings, based on their preferences, with  subexpressions  starting
     earlier in the RE taking priority over ones starting later. Note  that
     outer subexpressions thus take  priority    over    their    component
     subexpressions. 
     Note that the quantifiers {1,1}  and  {1,1}?  can  be  used  to  force
     longest and shortest preference, respectively, on a subexpression or a
     whole RE.
     Match lengths are measured in characters, not collating  elements.  An
     empty string is considered longer than no match at all.  For  example,
     bb*  matches    the    three    middle    characters    of    `abbbc',
     (week|wee)(night|knights) matches all ten characters of  `weeknights',
     when (.*).* is matched against  abc  the  parenthesized  subexpression
     matches all three characters, and when (a*)*  is  matched  against  bc
     both the whole RE and the parenthesized subexpression match  an  empty
     string. 
     If case-independent matching is specified, the effect is  much  as  if
     all  case  distinctions  had  vanished  from  the  alphabet.  When  an
     alphabetic that exists  in  multiple  cases  appears  as  an  ordinary
     character outside a bracket expression, it is effectively  transformed
     into a bracket expression containing both cases,  so  that  x  becomes
     `[xX]'.  When  it  appears  inside  a  bracket  expression,  all  case
     counterparts of it are added to the bracket expression,  so  that  [x]
     becomes [xX] and [^x] becomes `[^xX]'.
     If newline-sensitive matching is specified, . and bracket  expressions
     using ^ will never match the newline character (so that  matches  will
     never cross newlines unless the RE explicitly arranges it) and ^ and $
     will match the empty string after and before a  newline  respectively,
     in addition to matching at beginning and end of  string  respectively.
     ARE \A and \Z continue to match beginning or end of string only.
     If partial newline-sensitive matching is  specified,  this  affects  .
     and bracket expressions as with newline-sensitive matching, but not  ^
     and `$'.
     If inverse  partial  newline-sensitive  matching  is  specified,  this
     affects ^ and $ as with newline-sensitive  matching,  but  not  .  and
     bracket expressions. This  isn't  very  useful  but  is  provided  for
     symmetry. 

LIMITS AND COMPATIBILITY
     No particular limit is imposed on the length of REs. Programs intended
     to be highly portable should not employ REs longer than 256 bytes,  as
     a POSIX-compliant implementation can refuse to accept such REs.
     The only feature of AREs that  is  actually  incompatible  with  POSIX
     EREs is that \ does not lose its special significance  inside  bracket
     expressions. All other ARE features use syntax which is illegal or has
     undefined or unspecified effects in POSIX  EREs;  the  ***  syntax  of
     directors likewise is outside the POSIX syntax for both BREs and EREs.
      
     Many of the ARE extensions are borrowed from Perl, but some have  been
     changed to clean them up, and a few Perl extensions are  not  present.
     Incompatibilities of note include `\b',  `\B',  the  lack  of  special
     treatment for a trailing newline, the addition of complemented bracket
     expressions to the things affected by newline-sensitive matching,  the
     restrictions on parentheses and  back    references    in    lookahead
     constraints, and the longest/shortest-match (rather than  first-match)
     matching semantics.
     The matching rules for  REs  containing  both  normal  and  non-greedy
     quantifiers have  changed  since  early  beta-test  versions  of  this
     package. (The new rules are much simpler and cleaner, but  don't  work
     as hard at guessing the user's real intentions.)
     Henry Spencer's original 1986 regexp package, still in widespread  use
     (e.g., in pre-8.1 releases of Tcl), implemented an  early  version  of
     today's  EREs.  There  are  four  incompatibilities  between  regexp's
     near-EREs (`RREs' for short) and AREs. In roughly increasing order  of
     significance: 
               In AREs, \ followed by an alphanumeric character  is  either
               an escape or an error, while in RREs, it  was  just  another
               way of writing  the  alphanumeric.  This  should  not  be  a
               problem because there was no reason to write such a sequence
               in RREs.
               { followed by a digit in  an  ARE  is  the  beginning  of  a
               bound, while in RREs, { was always  an  ordinary  character.
               Such sequences should be rare, and will often result  in  an
               error because following characters  will  not  look  like  a
               valid bound.
               In AREs, \ remains a special character  within  `[]',  so  a
               literal \ within [] must be written `\\'. \\  also  gives  a
               literal \  within  []  in  RREs,  but  only  truly  paranoid
               programmers routinely doubled the backslash.
               AREs report the longest/shortest match for  the  RE,  rather
               than the first found in a specified search order.  This  may
               affect some RREs which were written in the expectation  that
               the first match would be reported. (The careful crafting  of
               RREs to optimize the  search  order  for  fast  matching  is
               obsolete (AREs examine all possible matches in parallel, and
               their performance is   largely    insensitive    to    their
               complexity) but cases where the search order  was  exploited
               to deliberately find a   match    which    was    not    the
               longest/shortest will need rewriting.)

BASIC REGULAR EXPRESSIONS
     BREs differ from EREs  in  several  respects.  `|',  `+',  and  ?  are
     ordinary characters and there   is    no    equivalent    for    their
     functionality. The delimiters for bounds are \{ and `\}', with { and }
     by themselves ordinary characters. The    parentheses    for    nested
     subexpressions are \( and `\)', with ( and )  by  themselves  ordinary
     characters. ^ is an ordinary character except at the beginning of  the
     RE or the beginning of a parenthesized subexpression, $ is an ordinary
     character except at the end of the RE or the end  of  a  parenthesized
     subexpression, and * is an ordinary character if  it  appears  at  the
     beginning of the RE or the beginning of a parenthesized  subexpression
     (after a possible leading `^'). Finally, single-digit back  references
     are available, and \< and \> are  synonyms  for  [[:<:]]  and  [[:>:]]
     respectively; no other escapes are available.


SEE ALSO
     RegExp, regexp, regsub, lsearch, switch, text

KEYWORDS 
     match, regular expression, string






_________________________________________________________________

NAME
     read - Read from a channel

SYNOPSIS
	read ?-nonewline? channelId
	read channelId numChars

_________________________________________________________________

DESCRIPTION 
     In the first form, the  read  command  reads  all  of  the  data  from
     channelId up to the end of the  file.  If  the  -nonewline  switch  is
     specified then the last character of the file is discarded if it is  a
     newline. In the second form, the extra  argument  specifies  how  many
     characters to read. Exactly that many  characters  will  be  read  and
     returned, unless there are fewer than numChars left in  the  file;  in
     this case all the remaining characters are returned. If the channel is
     configured to use a multi-byte encoding, then the number of characters
     read may not be the same as the number of bytes read.
     If channelId is in nonblocking mode, the command may not read as  many
     characters as requested: once all available input has been  read,  the
     command will return the data that is available  rather  than  blocking
     for more input. If the channel  is  configured  to  use  a  multi-byte
     encoding, then there may actually  be  some  bytes  remaining  in  the
     internal buffers that do not form a complete  character.  These  bytes
     will not be returned  until  a  complete  character  is  available  or
     end-of-file is reached.  The  -nonewline  switch  is  ignored  if  the
     command returns before reaching the end of the file.
     Read translates  end-of-line  sequences  in  the  input  into  newline
     characters according to the -translation option for the  channel.  See
     the fconfigure  manual  entry  for  a  discussion  on  ways  in  which
     fconfigure will alter input.


SEE ALSO
     file, eof, fblocked, fconfigure

KEYWORDS 
     blocking, channel, end  of  line,  end  of  file,  nonblocking,  read,
     translation, encoding






_________________________________________________________________

NAME
     regexp - Match a regular expression against a string

SYNOPSIS
	regexp ?switches? exp string ?matchVar? ?subMatchVar subMatchVar ...?

_________________________________________________________________

DESCRIPTION 
     Determines whether the regular expression exp matches part or  all  of
     string and returns 1 if it does, 0 if it doesn't,  unless  -inline  is
     specified (see below). (Regular expression matching  is  described  in
     the re_syntax reference page.)
     If additional arguments are  specified  after  string  then  they  are
     treated as the names of variables in which to return information about
     which part(s) of string matched exp. MatchVar will be set to the range
     of string that matched all of exp. The first subMatchVar will  contain
     the characters in  string  that  matched  the  leftmost  parenthesized
     subexpression within  exp,  the  next  subMatchVar  will  contain  the
     characters that matched the next parenthesized  subexpression  to  the
     right in exp, and so on.
     If the initial arguments to regexp start with - then they are  treated
     as switches. The following switches are currently supported:
          -about 
               Instead of  attempting  to  match  the  regular  expression,
               returns a list  containing  information  about  the  regular
               expression. The first element of the list is a subexpression
               count. The second element is a list of property  names  that
               describe various attributes of the regular expression.  This
               switch is primarily intended for debugging purposes.
          -expanded 
               Enables use of the expanded regular expression syntax  where
               whitespace and comments are ignored. This  is  the  same  as
               specifying the (?x) embedded option (see METASYNTAX, below).
                
          -indices 
               Changes what is  stored  in  the  subMatchVars.  Instead  of
               storing the matching characters from string,  each  variable
               will contain a  list  of  two  decimal  strings  giving  the
               indices in string of the first and last  characters  in  the
               matching range of characters.
          -line 
               Enables newline-sensitive matching. By default, newline is a
               completely ordinary character with no special meaning.  With
               this flag, `[^' bracket  expressions  and  `.'  never  match
               newline, `^' matches an empty string after  any  newline  in
               addition to its normal function, and `$'  matches  an  empty
               string before any newline in addition    to    its    normal
               function. This flag is equivalent   to    specifying    both
               -linestop and -lineanchor, or the (?n) embedded option  (see
               METASYNTAX, below).
          -linestop 
               Changes the behavior of `[^' bracket expressions and `.'  so
               that they stop at newlines. This is the same  as  specifying
               the (?p) embedded option (see METASYNTAX, below).
          -lineanchor 
               Changes the behavior of `^' and  `$'  (the  ``anchors'')  so
               they match the beginning and end  of  a  line  respectively.
               This is the same as specifying the (?w) embedded option (see
               METASYNTAX, below).
          -nocase 
               Causes upper-case characters in  string  to  be  treated  as
               lower case during the matching process.
          -all 
               Causes the regular expression to be matched as many times as
               possible in  the  string,  returning  the  total  number  of
               matches found. If this is specified  with  match  variables,
               they will continue information for the last match only.
          -inline 
               Causes the command to return, as a list, the data that would
               otherwise be placed in match variables. When using  -inline,
               match variables may not be specified. If used with -all, the
               list will be concatenated at each  iteration,  such  that  a
               flat list is always returned. For each match iteration,  the
               command will append the overall match data, plus one element
               for each subexpression in the regular  expression.  Examples
               are: regexp -inline -- {\w(\w)} " inlined " => {in n} regexp
               -all -inline -- {\w(\w)} " inlined " => {in n li i ne e}
          -start index
               Specifies a character index offset into the string to  start
               matching the regular expression at. When using this  switch,
               `^' will not match the beginning of the line,  and  \A  will
               still match the start of the string at index. If -indices is
               specified, the indices will be  indexed  starting  from  the
               absolute beginning  of  the  input  string.  index  will  be
               constrained to the bounds of the input string.
          -- 
               Marks the end of switches. The argument following  this  one
               will be treated as exp even if it starts with a -.
     If there are  more  subMatchVar's  than  parenthesized  subexpressions
     within exp, or if a particular subexpression in exp doesn't match  the
     string (e.g. because it was in a portion of the expression that wasn't
     matched), then the corresponding subMatchVar will be set to ``-1  -1''
     if -indices has been specified or to an empty string otherwise.


SEE ALSO
     re_syntax, regsub

KEYWORDS 
     match, regular expression, string





_________________________________________________________________

NAME
     registry - Manipulate the Windows registry

SYNOPSIS
	package require registry 1.0
	registry option keyName ?arg arg ...?

_________________________________________________________________

DESCRIPTION 
     The  registry  package  provides  a  general  set  of  operations  for
     manipulating the Windows registry. The package implements the registry
     Tcl command. This command is only supported on the  Windows  platform.
     Warning: this command should be  used  with  caution  as  a  corrupted
     registry can leave your system in an unusable state.
     KeyName is the name of a registry key. Registry keys must  be  one  of
     the following forms:
               \\hostname\rootname\keypath 
               rootname\keypath 
               rootname 

     Hostname specifies the name of any valid  Windows  host  that  exports
     its registry.  The    rootname    component    must    be    one    of
     HKEY_LOCAL_MACHINE, HKEY_USERS, HKEY_CLASSES_ROOT,  HKEY_CURRENT_USER,
     HKEY_CURRENT_CONFIG, HKEY_PERFORMANCE_DATA, or   HKEY_DYN_DATA.    The
     keypath can be one or more registry key names separated  by  backslash
     (\) characters.
     Option indicates what to do with the registry  key  name.  Any  unique
     abbreviation for option is acceptable. The valid options are:
          registry delete keyName ?valueName?
               If the optional valueName argument is present, the specified
               value under keyName will be deleted from  the  registry.  If
               the optional valueName is omitted, the specified key and any
               subkeys or values beneath it in the registry heirarchy  will
               be deleted. If the key could not be deleted then an error is
               generated. If the key did not  exist,  the  command  has  no
               effect. 
          registry get keyName valueName
               Returns the data associated with the value  valueName  under
               the key keyName. If either the key or  the  value  does  not
               exist, then an error is generated. For more details  on  the
               format of the returned data, see SUPPORTED TYPES, below.
          registry keys keyName ?pattern?
               If pattern isn't specified, returns a list of names  of  all
               the subkeys of keyName. If pattern is specified, only  those
               names matching pattern are returned. Matching is  determined
               using the same rules as for string match. If  the  specified
               keyName does not exist, then an error is generated.
          registry set keyName ?valueName data ?type??
               If valueName isn't specified, creates the key keyName if  it
               doesn't already exist. If valueName  is  specified,  creates
               the key  keyName  and  value  valueName  if  necessary.  The
               contents  of  valueName  are  set  to  data  with  the  type
               indicated by type. If type isn't specified, the type  sz  is
               assumed. For more details on the data  and  type  arguments,
               see SUPPORTED TYPES below.
          registry type keyName valueName
               Returns the type of the value valueName in the key  keyName.
               For more information on the possible  types,  see  SUPPORTED
               TYPES, below.
          registry values keyName ?pattern?
               If pattern isn't specified, returns a list of names  of  all
               the values of keyName. If pattern is specified,  only  those
               names matching pattern are returned. Matching is  determined
               using the same rules as for string match.

SUPPORTED TYPES
     Each value under a key  in  the  registry  contains  some  data  of  a
     particular  type  in  a  type-specific  representation.  The  registry
     command converts between this internal representation and one that can
     be manipulated by Tcl scripts. In  most  cases,  the  data  is  simply
     returned as a Tcl string. The type indicates the intended use for  the
     data, but does not actually change the representation. For some types,
     the registry command returns the data in a different form to  make  it
     easier to manipulate.  The  following  types  are  recognized  by  the
     registry command:
          binary 
               The registry value contains arbitrary binary data. The  data
               is represented exactly in Tcl, including any embedded nulls.
                
          none 
               The registry value contains arbitrary binary  data  with  no
               defined type.  The  data  is  represented  exactly  in  Tcl,
               including any embedded nulls.
          sz 
               The registry value contains a  null-terminated  string.  The
               data is represented in Tcl as a string.
          expand_sz 
               The registry value contains a  null-terminated  string  that
               contains unexpanded references to environment  variables  in
               the normal Windows style (for example, "%PATH%").  The  data
               is represented in Tcl as a string.
          dword 
               The registry value contains a little-endian  32-bit  number.
               The data is represented in Tcl as a decimal string.
          dword_big_endian 
               The registry value contains a big-endian 32-bit number.  The
               data is represented in Tcl as a decimal string.
          link 
               The registry value contains a symbolic  link.  The  data  is
               represented exactly in Tcl, including any embedded nulls.
          multi_sz 
               The registry value  contains  an  array  of  null-terminated
               strings. The data  is  represented  in  Tcl  as  a  list  of
               strings. 
          resource_list 
               The registry value contains a device-driver  resource  list.
               The data  is  represented  exactly  in  Tcl,  including  any
               embedded nulls.
     In addition to the symbolically  named  types  listed  above,  unknown
     types are identified using a 32-bit integer that  corresponds  to  the
     type code returned by the system interfaces. In this case, the data is
     represented exactly in Tcl, including any embedded nulls.


PORTABILITY ISSUES
     The registry command is only available on Windows.


KEYWORDS 
     registry 





_________________________________________________________________

NAME
     regsub - Perform substitutions based  on  regular  expression  pattern
     matching 

SYNOPSIS
	regsub ?switches? exp string subSpec varName

_________________________________________________________________

DESCRIPTION 
     This command matches the regular expression exp against string, and it
     copies string to the variable whose name is given by varName. (Regular
     expression matching is described in the re_syntax reference page.)  If
     there is a match, then while copying string to varName the portion  of
     string that matched exp is replaced with subSpec. If subSpec  contains
     a ``&'' or ``\0'', then it is replaced in the  substitution  with  the
     portion of string that matched exp.  If  subSpec  contains  a  ``\n'',
     where n is a digit between 1  and  9,  then  it  is  replaced  in  the
     substitution  with  the  portion  of  string  that  matched  the  n-th
     parenthesized subexpression of exp. Additional backslashes may be used
     in subSpec to prevent special interpretation of  ``&''  or  ``\0''  or
     ``\n'' or backslash. The  use  of  backslashes  in  subSpec  tends  to
     interact badly with the Tcl  parser's  use  of  backslashes,  so  it's
     generally safest to enclose subSpec in  braces    if    it    includes
     backslashes. 
     If the initial arguments to regexp start with - then they are  treated
     as switches. The following switches are currently supported:
          -all 
               All ranges in string that match   exp    are    found    and
               substitution is performed for each of these ranges.  Without
               this switch only the  first  matching  range  is  found  and
               substituted. If -all is specified,  then  ``&''  and  ``\n''
               sequences  are  handled  for  each  substitution  using  the
               information from the corresponding match.
          -expanded 
               Enables use of the expanded regular expression syntax  where
               whitespace and comments are ignored. This  is  the  same  as
               specifying the (?x) embedded option (see METASYNTAX, below).
                
          -line 
               Enables newline-sensitive matching. By default, newline is a
               completely ordinary character with no special meaning.  With
               this flag, `[^' bracket  expressions  and  `.'  never  match
               newline, `^' matches an empty string after  any  newline  in
               addition to its normal function, and `$'  matches  an  empty
               string before any newline in addition    to    its    normal
               function. This flag is equivalent   to    specifying    both
               -linestop and -lineanchor, or the (?n) embedded option  (see
               METASYNTAX, below).
          -linestop 
               Changes the behavior of `[^' bracket expressions and `.'  so
               that they stop at newlines. This is the same  as  specifying
               the (?p) embedded option (see METASYNTAX, below).
          -lineanchor 
               Changes the behavior of `^' and  `$'  (the  ``anchors'')  so
               they match the beginning and end  of  a  line  respectively.
               This is the same as specifying the (?w) embedded option (see
               METASYNTAX, below).
          -nocase 
               Upper-case characters in string will   be    converted    to
               lower-case before    matching    against    exp;    however,
               substitutions specified by subSpec    use    the    original
               unconverted form of string.
          -start index
               Specifies a character index offset into the string to  start
               matching the regular expression at. When using this  switch,
               `^' will not match the beginning of the line,  and  \A  will
               still match the start of the string at index. index will  be
               constrained to the bounds of the input string.
          -- 
               Marks the end of switches. The argument following  this  one
               will be treated as exp even if it starts with a -.
     The command returns a count of the  number  of  matching  ranges  that
     were found and replaced. See the manual entry for regexp  for  details
     on the interpretation of regular expressions.


SEE ALSO
     regexp, re_syntax

KEYWORDS 
     match, pattern, regular expression, substitute







_________________________________________________________________

NAME
     rename - Rename or delete a command

SYNOPSIS
	rename oldName newName

_________________________________________________________________

DESCRIPTION 
     Rename the command that used to be called oldName so that  it  is  now
     called newName. If newName is an empty string then oldName is deleted.
     oldName  and  newName  may  include  namespace  qualifiers  (names  of
     containing namespaces). If a  command  is  renamed  into  a  different
     namespace, future invocations of it will execute in the new namespace.
     The rename command returns an empty string as result.


SEE ALSO
     namespace, proc

KEYWORDS 
     command, delete, namespace, rename






_________________________________________________________________

NAME
     resource - Manipulate Macintosh resources

SYNOPSIS
	resource option ?arg arg ...?

_________________________________________________________________

DESCRIPTION 
     The resource command provides some generic operations for dealing with
     Macintosh resources. This command is only supported on  the  Macintosh
     platform. Each Macintosh file consists of two forks: a data fork and a
     resource fork. You use the normal open, puts, close, etc. commands  to
     manipulate the data fork. You  must  use  this  command,  however,  to
     interact with  the  resource  fork.  Option  indicates  what  resource
     command to perform. Any unique abbreviation for option is  acceptable.
     The valid options are:
          resource close rsrcRef
               Closes the given resource reference (obtained from  resource
               open). Resources from that resource file will no  longer  be
               available. 
          resource delete ?options? resourceType
               This command will delete the resource specified  by  options
               and  type  resourceType  (see  RESOURCE  TYPES  below).  The
               options give you several ways to specify the resource to  be
               deleted. 
                    -id resourceId
                         If the -id option is given the id resourceId  (see
                         RESOURCE IDS below) is used   to    specify    the
                         resource to be deleted. The id must be a number  -
                         to specify a name use the -name option.
                    -name resourceName
                         If -name is specified,    the    resource    named
                         resourceName will be deleted. If the -id  is  also
                         provided, then there must be a resource with  BOTH
                         this name and this id. If  no  name  is  provided,
                         then the id will be used regardless of the name of
                         the actual resource.
                    -file resourceRef
                         If the -file option is specified then the resource
                         will be  deleted  from  the  file  pointed  to  by
                         resourceRef. Otherwise the first resource with the
                         given resourceName  and  or  resourceId  which  is
                         found on the resource file path will  be  deleted.
                         To inspect the file path, use the  resource  files
                         command. 
          resource files ?resourceRef?
               If resourceRefis not provided, this command  returns  a  Tcl
               list of the resource references for all the  currently  open
               resource files. The list is in the normal  Macintosh  search
               order  for  resources.  If  resourceRef  is  specified,  the
               command will return the path to the file whose resource fork
               is represented by that token.
          resource list resourceType ?resourceRef?
               List all of the resources  ids  of  type  resourceType  (see
               RESOURCE TYPES below). If resourceRef is specified then  the
               command will limit the search to  that  particular  resource
               file. Otherwise, all resource files currently opened by  the
               application will be searched.  A  Tcl  list  of  either  the
               resource name's or resource id's of the found resources will
               be returned. See the RESOURCE IDS  section  below  for  more
               details about what a resource id is.
          resource open fileName ?access?
               Open the resource  for  the  file  fileName.  Standard  file
               access permissions may also be  specified  (see  the  manual
               entry for open for   details).    A    resource    reference
               (resourceRef) is returned that can  be  used  by  the  other
               resource commands. An error can occur if  the  file  doesn't
               exist or the file does not have a resource fork. However, if
               you open the file with write  permissions  the  file  and/or
               resource fork will  be  created  instead  of  generating  an
               error. 
          resource read resourceType resourceId ?resourceRef?
               Read the entire resource of type resourceType (see  RESOURCE
               TYPES below) and the name or id of resourceId (see  RESOURCE
               IDS below) into memory and return the result. If resourceRef
               is specified we limit our  search  to  that  resource  file,
               otherwise we search all open  resource    forks    in    the
               application. It is important to  note  that  most  Macintosh
               resource use a binary format and the data returned from this
               command may have embedded NULLs or other non-ASCII data.
          resource types ?resourceRef?
               This command returns a Tcl list of all resource  types  (see
               RESOURCE TYPES below) found in the resource file pointed  to
               by resourceRef. If resourceRef  is  not  specified  it  will
               return all the resource types found in every  resource  file
               currently opened by the application.
          resource write ?options? resourceType data
               This command will write the passed in data as a new resource
               of type resourceType (see  RESOURCE  TYPES  below).  Several
               options are  available  that  describe  where  and  how  the
               resource is stored.
                    -id resourceId
                         If the -id option is given the id resourceId  (see
                         RESOURCE IDS below) is used for the new  resource,
                         otherwise a unique id will be generated that  will
                         not conflict with any existing resource.  However,
                         the id must be a number - to specify  a  name  use
                         the -name option.
                    -name resourceName
                         If -name is specified the resource will  be  named
                         resourceName, otherwise it  will  have  the  empty
                         string as the name.
                    -file resourceRef
                         If the -file option is specified then the resource
                         will be written in the file    pointed    to    by
                         resourceRef,  otherwise  the  most  resently  open
                         resource will be used.
                    -force 
                         If the target resource  already  exists,  then  by
                         default Tcl will not overwrite it,  but  raise  an
                         error  instead.  Use  the  -force  flag  to  force
                         overwriting the extant resource.
RESOURCE TYPES
     Resource types are defined as a four character  string  that  is  then
     mapped to an underlying id. For example, TEXT refers to the  Macintosh
     resource type for text. The type STR# is a list  of  counted  strings.
     All Macintosh resources must be of   some    type.    See    Macintosh
     documentation for a more complete list  of  resource  types  that  are
     commonly used.


RESOURCE IDS
     For this command the notion of a resource id actually  refers  to  two
     ideas in Macintosh resources. Every place you can use  a  resource  Id
     you can use either the resource name or a resource number.  Names  are
     always searched or returned in preference to numbers. For example, the
     resource list command will return names if they exist  or  numbers  if
     the name is NULL.


PORTABILITY ISSUES
     The resource command is only available on Macintosh.


SEE ALSO
     open 

KEYWORDS 
     open, resource





_________________________________________________________________

NAME
     return - Return from a procedure

SYNOPSIS
	return ?-code code? ?-errorinfo info? ?-errorcode code? ?string?

_________________________________________________________________

DESCRIPTION 
     Return immediately from the current procedure (or top-level command or
     source command), with string as the return value.  If  string  is  not
     specified then an empty string will be returned as result.


EXCEPTIONAL RETURNS
     In the usual case where the -code option isn't specified the procedure
     will return normally (its completion code will  be  TCL_OK).  However,
     the -code option may be used to generate an  exceptional  return  from
     the procedure. Code may have any of the following values:
          ok 
               Normal return: same as if the option is omitted.
          error 
               Error return: same as if the  error  command  were  used  to
               terminate the procedure, except for  handling  of  errorInfo
               and errorCode variables (see below).
          return 
               The current procedure will return with a completion code  of
               TCL_RETURN, so that  the  procedure  that  invoked  it  will
               return also.
          break 
               The current procedure will return with a completion code  of
               TCL_BREAK, which will terminate the innermost nested loop in
               the code that invoked the current procedure.
          continue 
               The current procedure will return with a completion code  of
               TCL_CONTINUE, which will terminate the current iteration  of
               the innermost nested loop  in  the  code  that  invoked  the
               current procedure.
          value 
               Value must be  an  integer;  it  will  be  returned  as  the
               completion code for the current procedure.
     The -code option is rarely used. It is  provided  so  that  procedures
     that implement new control structures    can    reflect    exceptional
     conditions back to their callers.
     Two additional options, -errorinfo and  -errorcode,  may  be  used  to
     provide additional information during error returns. These options are
     ignored unless code is error.
     The -errorinfo  option  specifies  an  initial  stack  trace  for  the
     errorInfo variable; if it is not specified then the stack  trace  left
     in errorInfo will include the call to the procedure and higher  levels
     on the stack but it will not include any information about the context
     of the error  within  the  procedure.  Typically  the  info  value  is
     supplied from the value  left  in  errorInfo  after  a  catch  command
     trapped an error within the procedure.
     If the -errorcode option is specified then code provides a  value  for
     the errorCode variable. If the option is not specified then  errorCode
     will default to NONE.


SEE ALSO
     break, continue, error, proc

KEYWORDS 
     break, continue, error, procedure, return






_________________________________________________________________

NAME
     SafeBase - A mechanism  for    creating    and    manipulating    safe
     interpreters. 

SYNOPSIS
	::safe::interpCreate ?slave? ?options...?
	::safe::interpInit slave ?options...?
	::safe::interpConfigure slave ?options...?
	::safe::interpDelete slave
	::safe::interpAddToAccessPath slave directory
	::safe::interpFindInAccessPath slave directory
	::safe::setLogCmd ?cmd arg...?

OPTIONS 
     ?-accessPath pathList? ?-statics  boolean?    ?-noStatics?    ?-nested
     boolean? ?-nestedLoadOk? ?-deleteHook script?

_________________________________________________________________

DESCRIPTION 
     Safe Tcl is a mechanism for executing untrusted Tcl scripts safely and
     for providing mediated access by such scripts to potentially dangerous
     functionality. 
     The Safe Base ensures that  untrusted  Tcl  scripts  cannot  harm  the
     hosting application. The Safe  Base  prevents  integrity  and  privacy
     attacks. Untrusted Tcl scripts are prevented from corrupting the state
     of the hosting application or computer.  Untrusted  scripts  are  also
     prevented from disclosing information stored on the  hosting  computer
     or in the hosting application to any party.
     The Safe Base allows a master interpreter to create  safe,  restricted
     interpreters that contain a set of predefined aliases for the  source,
     load, file, encoding, and exit  commands  and  are  able  to  use  the
     auto-loading and package mechanisms.
     No knowledge of the file  system  structure  is  leaked  to  the  safe
     interpreter,  because  it  has  access  only  to  a  virtualized  path
     containing tokens. When the safe  interpreter  requests  to  source  a
     file, it uses the token in the virtual path as part of the  file  name
     to source; the master interpreter transparently translates  the  token
     into a real directory name and executes the requested  operation  (see
     the section SECURITY below for details). Different levels of  security
     can be selected by using the optional flags of the commands  described
     below. 
     All commands provided in the  master  interpreter  by  the  Safe  Base
     reside in the safe namespace:


COMMANDS 
     The following commands are provided in the master interpreter:
          ::safe::interpCreate ?slave? ?options...?
               Creates a safe interpreter, installs the  aliases  described
               in the section ALIASES and initializes the auto-loading  and
               package mechanism as specified by the supplied options.  See
               the OPTIONS section below for a description of the  optional
               arguments. If the slave argument is omitted, a name will  be
               generated.  ::safe::interpCreate    always    returns    the
               interpreter name.
          ::safe::interpInit slave ?options...?
               This command is similar to interpCreate except it that  does
               not create  the  safe  interpreter.  slave  must  have  been
               created by some other means, like interp create -safe.
          ::safe::interpConfigure slave ?options...?
               If no options  are  given,  returns  the  settings  for  all
               options for the named safe interpreter as a list of  options
               and their  current  values  for  that  slave.  If  a  single
               additional argument is provided, it will return a list of  2
               elements name and value where name is the full name of  that
               option and value the current value for that option  and  the
               slave. If more than two additional arguments  are  provided,
               it will reconfigure the safe interpreter and change each and
               only the provided options. See the section on OPTIONS  below
               for options description. Example of  use:  #  Create  a  new
               interp with the same configuration as "$i0" : set  i1  [eval
               safe::interpCreate [safe::interpConfigure $i0]]  #  Get  the
               current deleteHook set dh [safe::interpConfigure $i0 -del] #
               Change (only) the statics loading ok attribute of an  interp
               # and its deleteHook (leaving the    rest    unchanged)    :
               safe::interpConfigure $i0 -delete {foo bar} -statics 0 ;
          ::safe::interpDelete slave
               Deletes the safe interpreter and cleans up the corresponding
               master interpreter data structures. If a  deleteHook  script
               was specified for this interpreter it  is  evaluated  before
               the interpreter is deleted, with the name of the interpreter
               as an additional argument.
          ::safe::interpFindInAccessPath slave directory
               This command finds  and  returns  the  token  for  the  real
               directory directory in the  safe    interpreter's    current
               virtual access path. It generates an error if the  directory
               is  not  found.  Example  of  use:  $slave  eval  [list  set
               tk_library      [::safe::interpFindInAccessPath        $name
               $tk_library]] 
          ::safe::interpAddToAccessPath slave directory
               This command adds directory to the virtual  path  maintained
               for the safe interpreter in  the  master,  and  returns  the
               token that can be used in the  safe  interpreter  to  obtain
               access to files in  that  directory.  If  the  directory  is
               already in the virtual  path,  it  only  returns  the  token
               without adding the directory  to  the  virtual  path  again.
               Example of use: $slave    eval    [list    set    tk_library
               [::safe::interpAddToAccessPath $name $tk_library]]
          ::safe::setLogCmd ?cmd arg...?
               This command installs a script  that  will  be  called  when
               interesting life cycle events occur for a safe  interpreter.
               When called with no  arguments,  it  returns  the  currently
               installed script. When called with one  argument,  an  empty
               string,  the  currently  installed  script  is  removed  and
               logging is turned off. The script will be invoked  with  one
               additional  argument,  a  string  describing  the  event  of
               interest. The main purpose is  to  help  in  debugging  safe
               interpreters. Using this facility you can get complete error
               messages while the safe interpreter gets only generic  error
               messages. This  prevents  a  safe  interpreter  from  seeing
               messages about failures and other events that might  contain
               sensitive information such as real directory names.
                         Example  of  use:  ::safe::setLogCmd  puts  stderr
                         Below is the output of a sample session in which a
                         safe interpreter attempted to source  a  file  not
                         found in its virtual access path.  Note  that  the
                         safe interpreter only received  an  error  message
                         saying that the file was  not  found:  NOTICE  for
                         slave interp10 : Created NOTICE for slave interp10
                         :  Setting    accessPath=(/foo/bar)    staticsok=1
                         nestedok=0 deletehook=() NOTICE for slave interp10
                         : auto_path in interp10 has been set to  {$p(:0:)}
                         ERROR for slave interp10 :  /foo/bar/init.tcl:  no
                         such file or directory

OPTIONS 
     The following  options    are    common    to    ::safe::interpCreate,
     ::safe::interpInit, and ::safe::interpConfigure. Any option  name  can
     be abbreviated to its minimal non-ambiguous name. Option names are not
     case sensitive.
          -accessPath directoryList
               This option sets the list of directories from which the safe
               interpreter can source and load files. If this option is not
               specified, or if it is given as the  empty  list,  the  safe
               interpreter will use the same directories as its master  for
               auto-loading. See the section SECURITY below for more detail
               about virtual paths, tokens and access control.
          -statics boolean
               This option  specifies  if  the  safe  interpreter  will  be
               allowed to load statically linked  packages  (like  load  {}
               Tk). The default value  is  true  :  safe  interpreters  are
               allowed to load statically linked packages.
          -noStatics 
               This option is a convenience shortcut for -statics false and
               thus specifies that the safe interpreter will not be allowed
               to load statically linked packages.
          -nested boolean
               This option  specifies  if  the  safe  interpreter  will  be
               allowed to load packages into its own sub-interpreters.  The
               default value is false : safe interpreters are  not  allowed
               to load packages into their own sub-interpreters.
          -nestedLoadOk 
               This option is a convenience shortcut for -nested  true  and
               thus specifies the safe interpreter will be allowed to  load
               packages into its own sub-interpreters.
          -deleteHook script
               When this option is given an non empty script,  it  will  be
               evaluated in the master with the   name    of    the    safe
               interpreter as an additional argument just  before  actually
               deleting the safe interpreter. Giving an empty value removes
               any currently installed deletion hook script for  that  safe
               interpreter. The default value  ({})  is  not  to  have  any
               deletion call back.
ALIASES 
     The following aliases are provided in a safe interpreter:
          source fileName
               The requested file, a Tcl source file, is sourced  into  the
               safe interpreter if it is found. The source alias  can  only
               source files from directories in the virtual  path  for  the
               safe interpreter. The source alias   requires    the    safe
               interpreter to use one of the token  names  in  its  virtual
               path to denote the directory in which the file to be sourced
               can be found. See the section  on    SECURITY    for    more
               discussion of restrictions on valid filenames.
          load fileName
               The requested file, a shared  object  file,  is  dynamically
               loaded into  the  safe  interpreter  if  it  is  found.  The
               filename must contain a token name mentioned in the  virtual
               path for the safe interpreter for    it    to    be    found
               successfully. Additionally,  the  shared  object  file  must
               contain a safe entry point; see the manual page for the load
               command for more details.
          file ?subCmd args...?
               The file alias provides access  to  a  safe  subset  of  the
               subcommands of the file command;  it  allows  only  dirname,
               join, extension, root, tail, pathname and split subcommands.
               For more details on what these subcommands do see the manual
               page for the file command.
          encoding ?subCmd args...?
               The enconding alias provides access to a safe subset of  the
               subcommands of the encoding command; it disallows setting of
               the  system  encoding,  but  allows  all  other  subcommands
               including system to check the current encoding.
          exit 
               The calling interpreter is deleted and  its  computation  is
               stopped, but the  Tcl  process  in  which  this  interpreter
               exists is not terminated.

SECURITY 
     The Safe Base does not attempt to  completely  prevent  annoyance  and
     denial of service attacks. These forms  of    attack    prevent    the
     application or user from temporarily using  the  computer  to  perform
     useful work, for example by consuming all available CPU  time  or  all
     available screen real estate. These attacks,  while  aggravating,  are
     deemed to be of  lesser  importance  in  general  than  integrity  and
     privacy attacks that the Safe Base is to prevent.
     The commands available in a safe interpreter, in addition to the  safe
     set as defined in interp manual page, are mediated aliases for source,
     load, exit, and safe subsets of file   and    encoding.    The    safe
     interpreter can also auto-load code and it can request  that  packages
     be loaded.
     Because some of these commands access the local file system, there  is
     a potential for information leakage about its directory structure.  To
     prevent this, commands that take file names as  arguments  in  a  safe
     interpreter use tokens instead of  the  real  directory  names.  These
     tokens are translated to the real directory name while a  request  to,
     e.g., source a file  is  mediated  by  the  master  interpreter.  This
     virtual path system is maintained in the master interpreter  for  each
     safe interpreter created by  ::safe::interpCreate  or  initialized  by
     ::safe::interpInit and the path maps tokens  accessible  in  the  safe
     interpreter into real  path  names  on  the  local  file  system  thus
     preventing safe interpreters from gaining    knowledge    about    the
     structure of the file system of the host on which the  interpreter  is
     executing. The only valid file names arguments for the source and load
     aliases provided to the slave are path in the form of [file join token
     filename] (ie, when using the native file path formats: token/filename
     on Unix, token\filename on Windows, and token:filename  on  the  Mac),
     where token is representing one of the directories of  the  accessPath
     list and filename is one file in that directory  (no  sub  directories
     access are allowed).
     When a token is used in a safe interpreter in a request to  source  or
     load a file, the token is checked and translated to a real  path  name
     and the file to be sourced or loaded is located on  the  file  system.
     The safe interpreter never gains knowledge of  the  actual  path  name
     under which the file is stored on the file system.
     To further prevent potential information leakage from sensitive  files
     that are accidentally included in the set of files that can be sourced
     by a safe interpreter, the source  alias  restricts  access  to  files
     meeting  the  following  constraints:  the  file  name  must  fourteen
     characters or shorter, must not contain more than one dot ("."),  must
     end up with the extension .tcl or be called tclIndex.
     Each element of the initial access path list will be assigned a  token
     that will be set in the slave auto_path and the first element of  that
     list will be set as the tcl_library for that slave.
     If the access path argument is not given or is  the  empty  list,  the
     default behavior is to let the slave access the same packages  as  the
     master has access to (Or to be more precise: only packages written  in
     Tcl (which by definition can't be dangerous as they run in  the  slave
     interpreter) and C extensions that provides a Safe_Init entry  point).
     For that purpose, the master's auto_path will be used to construct the
     slave access path. In order that the slave successfully loads the  Tcl
     library files (which includes the auto-loading mechanism  itself)  the
     tcl_library will be added or moved to the first position if necessary,
     in the slave access path, so the slave tcl_library will be the same as
     the master's (its real path will  still  be  invisible  to  the  slave
     though). In order that auto-loading works the same for the  slave  and
     the master in this by default case, the first-level sub directories of
     each directory in the master auto_path will  also  be  added  (if  not
     already included) to the slave access path. You can always  specify  a
     more restrictive path for which sub directories will never be searched
     by explicitly specifying your directory list with the -accessPath flag
     instead of relying on this default mechanism.
     When the accessPath is changed after    the    first    creation    or
     initialization  (ie  through  interpConfigure  -accessPath  list),  an
     auto_reset is automatically  evaluated  in  the  safe  interpreter  to
     synchronize its auto_index with the new token list.


SEE ALSO
     interp, library, load, package, source, unknown

KEYWORDS 
     alias, auto-loading,  auto_mkindex,  load,  master  interpreter,  safe
     interpreter, slave interpreter, source





_________________________________________________________________

NAME
     scan - Parse string using conversion specifiers in the style of sscanf
      

SYNOPSIS
	scan string format ?varName varName ...?

INTRODUCTION 
     This command parses fields from an input string in the same fashion as
     the ANSI C sscanf procedure and returns  a  count  of  the  number  of
     conversions performed, or -1 if the end of the input string is reached
     before any conversions have been performed. String gives the input  to
     be parsed and format indicates how to parse  it,  using  %  conversion
     specifiers as in sscanf. Each varName gives the name  of  a  variable;
     when a field is scanned from string the result is converted back  into
     a string and assigned to the corresponding  variable.  If  no  varName
     variables  are  specified,  then  scan  works  in  an  inline  manner,
     returning the data that would otherwise be stored in the variables  as
     a list. In the inline case, an empty string is returned when  the  end
     of the input string  is  reached  before  any  conversions  have  been
     performed. 


DETAILS ON SCANNING
     Scan operates by scanning string and  format  together.  If  the  next
     character in format is a blank or tab then it matches  any  number  of
     white space characters in string (including zero).  Otherwise,  if  it
     isn't a % character then it must match the next character  of  string.
     When a % is encountered  in  format,  it  indicates  the  start  of  a
     conversion specifier. A  conversion  specifier  contains  up  to  four
     fields after the %: a *, which indicates that the converted  value  is
     to be discarded instead of assigned to a  variable;  a  XPG3  position
     specifier; a number indicating a maximum field width; and a conversion
     character. All of these fields are optional except for the  conversion
     character. The fields that are present must appear in the order  given
     above. 
     When scan finds a conversion specifier in format, it first  skips  any
     white-space characters in string (unless the specifier  is  [  or  c).
     Then it converts the next input characters according to the conversion
     specifier and stores the result in the  variable  given  by  the  next
     argument to scan.
     If the % is followed by a decimal number and  a  $,  as  in  ``%2$d'',
     then the variable to  use  is  not  taken  from  the  next  sequential
     argument. Instead, it is taken from  the  argument  indicated  by  the
     number, where 1 corresponds to the first varName.  If  there  are  any
     positional specifiers in format then all of  the  specifiers  must  be
     positional. Every varName on the  argument  list  must  correspond  to
     exactly one conversion specifier or an error is generated, or  in  the
     inline case, any position can be specified at most once and the  empty
     positions will be filled in with empty strings.
     The following conversion characters are supported:
          d 
               The input field must be a decimal integer. It is read in and
               the value is stored in the variable as a decimal string.
          o 
               The input field must be an octal integer. It is read in  and
               the value is stored in the variable as a decimal string.
          x 
               The input field must be a hexadecimal integer. It is read in
               and the value is stored in the variable as a decimal string.
                
          u 
               The input field must be a  decimal  integer.  The  value  is
               stored in  the  variable  as  an  unsigned  decimal  integer
               string. 
          i 
               The input field must be an integer. The base (i.e.  decimal,
               octal, or hexadecimal) is determined in the same fashion  as
               described in expr. The value is stored in the variable as  a
               decimal string.
          c 
               A single character is read in and its binary value is stored
               in the variable as a decimal string. Initial white space  is
               not skipped in this case,  so  the  input  field  may  be  a
               white-space character. This conversion is different from the
               ANSI standard in that the input field always consists  of  a
               single character and no field width may be specified.
          s 
               The input field consists of all the  characters  up  to  the
               next white-space character; the characters are copied to the
               variable. 
          e or f or g
               The input field must be a floating-point  number  consisting
               of an optional sign, a string  of  decimal  digits  possibly
               containing a decimal point, and   an    optional    exponent
               consisting of an e or E followed by an optional sign  and  a
               string of decimal digits. It is read in and  stored  in  the
               variable as a floating-point string.
          [chars] 
               The input field consists of  any  number  of  characters  in
               chars. The matching string is stored in the variable. If the
               first character between the brackets  is  a  ]  then  it  is
               treated as part of chars rather than the closing bracket for
               the set. If chars contains a sequence of the form  a-b  then
               any character between a and b (inclusive) will match. If the
               first or last character between the brackets is a -, then it
               is treated as part of chars rather than indicating a range.
          [^chars] 
               The input field consists of any number of characters not  in
               chars. The matching string is stored in the variable. If the
               character immediately following the ^ is  a  ]  then  it  is
               treated as part of the set rather than the  closing  bracket
               for the set. If chars contains a sequence of  the  form  a-b
               then any character between  a  and  b  (inclusive)  will  be
               excluded from the  set.  If  the  first  or  last  character
               between the brackets is a -, then it is treated as  part  of
               chars rather than indicating a range.
          n 
               No input is consumed from the  input  string.  Instead,  the
               total number of chacters scanned from the  input  string  so
               far is stored in the variable.
     The number of characters read from the input for a conversion  is  the
     largest number that makes sense for that particular  conversion  (e.g.
     as many decimal digits as possible for %d, as  many  octal  digits  as
     possible for %o, and so on). The input field for  a  given  conversion
     terminates either when a white-space character is encountered or  when
     the maximum field width has been reached, whichever comes first. If  a
     * is present in the conversion specifier then no variable is  assigned
     and the next scan argument is not consumed.


DIFFERENCES FROM ANSI SSCANF
     The behavior of the scan command is the same as the  behavior  of  the
     ANSI C sscanf procedure except for the following differences:
          [1] 
               %p conversion specifier is not currently supported.
          [2] 
               For %c conversions a single character value is converted  to
               a decimal string, which  is    then    assigned    to    the
               corresponding varName; no field width may be  specified  for
               this conversion.
          [3] 
               The l, h, and L modifiers are ignored;  integer  values  are
               always converted as if there were no  modifier  present  and
               real values are always converted as if the l  modifier  were
               present (i.e. type double is  used    for    the    internal
               representation). 
          [4] 
               If the end  of  the  input  string  is  reached  before  any
               conversions have been performed and no variables are  given,
               and empty string is returned.

                
      
SEE ALSO
     format, sscanf

KEYWORDS 
     conversion specifier, parse, scan







_________________________________________________________________

NAME
     seek - Change the access position for an open channel

SYNOPSIS
	seek channelId offset ?origin?

_________________________________________________________________

DESCRIPTION 
     Changes the current access position for channelId. ChannelId must be a
     channel identifier such as returned from a previous invocation of open
     or socket. The offset and origin arguments  specify  the  position  at
     which the next read or write will occur for channelId. Offset must  be
     an integer (which may be negative) and  origin  must  be  one  of  the
     following: 
          start 
               The new access position will be offset bytes from the  start
               of the underlying file or device.
          current 
               The new access  position  will  be  offset  bytes  from  the
               current access position; a negative offset moves the  access
               position backwards in the underlying file or device.
          end 
               The new access position will be offset bytes from the end of
               the file or device. A  negative  offset  places  the  access
               position before the end  of  file,  and  a  positive  offset
               places the access position after the end of file.
     The origin argument defaults to start.
     The command flushes all buffered output for  the  channel  before  the
     command returns, even if the channel is in nonblocking mode.  It  also
     discards any buffered and unread input. This command returns an  empty
     string. An error occurs if this command is applied to  channels  whose
     underlying file or device does not support seeking.
     Note that offset values are byte offsets, not character offsets.  Both
     seek and tell operate in terms of bytes, not characters, unlike read.


SEE ALSO
     file, open, close, gets, tell

KEYWORDS 
     access position, file, seek






_________________________________________________________________

NAME
     set - Read and write variables

SYNOPSIS
	set varName ?value?

_________________________________________________________________

DESCRIPTION 
     Returns the value of variable varName. If value is specified, then set
     the value of varName to value, creating a new variable if one  doesn't
     already exist, and return its  value.  If  varName  contains  an  open
     parenthesis and ends with a close parenthesis, then it  refers  to  an
     array element: the characters before the first  open  parenthesis  are
     the name of the array, and the characters between the parentheses  are
     the index within the array.  Otherwise  varName  refers  to  a  scalar
     variable. Normally, varName is unqualified (does not include the names
     of any containing namespaces), and the variable of that  name  in  the
     current namespace is read or written. If  varName  includes  namespace
     qualifiers (in the array name if it refers to an array  element),  the
     variable in the specified namespace is read or written.
     If no  procedure  is  active,  then  varName  refers  to  a  namespace
     variable (global variable if  the  current  namespace  is  the  global
     namespace). If a  procedure  is  active,  then  varName  refers  to  a
     parameter or local variable of the procedure unless the global command
     was invoked to declare varName to be  global,  or  unless  a  variable
     command was invoked to declare varName to be a namespace variable.


SEE ALSO
     expr, proc, trace, unset

KEYWORDS 
     read, write, variable






_________________________________________________________________

NAME
     socket - Open a TCP network connection

SYNOPSIS
	socket ?options? host port
	socket -server command ?options? port

_________________________________________________________________

DESCRIPTION 
     This command opens a network socket and returns a  channel  identifier
     that may be used in future invocations of commands like read, puts and
     flush. At present only the TCP network protocol is  supported;  future
     releases may include support  for  additional  protocols.  The  socket
     command may be used to open either the client  or  server  side  of  a
     connection, depending on whether the -server switch is specified.


CLIENT SOCKETS
     If the -server option is not specified, then  the  client  side  of  a
     connection is opened and the command returns a channel identifier that
     can be used for both reading and writing. Port and host specify a port
     to connect to; there must be a server accepting  connections  on  this
     port. Port is an integer port number and host is either a domain-style
     name such as  www.sunlabs.com  or  a  numerical  IP  address  such  as
     127.0.0.1. Use localhost to refer to the host on which the command  is
     invoked. 
     The following options may also  be  present  before  host  to  specify
     additional information about the connection:
          -myaddr addr
               Addr gives the domain-style name or numerical IP address  of
               the client-side network interface to use for the connection.
               This option may be useful if the client machine has multiple
               network interfaces.  If  the  option  is  omitted  then  the
               client-side interface will be chosen by the system software.
                
          -myport port
               Port specifies  an  integer  port  number  to  use  for  the
               client's side of the connection. If this option is  omitted,
               the client's port number will be chosen  at  random  by  the
               system software.
          -async 
               The -async  option  will  cause  the  client  socket  to  be
               connected asynchronously. This means that the socket will be
               created immediately but may not  yet  be  connected  to  the
               server, when the call to socket  returns.  When  a  gets  or
               flush is done on the socket before  the  connection  attempt
               succeeds or fails, if the socket is in  blocking  mode,  the
               operation will wait until the  connection  is  completed  or
               fails. If the socket is in nonblocking mode and  a  gets  or
               flush is done on the socket before  the  connection  attempt
               succeeds or fails, the  operation  returns  immediately  and
               fblocked on the socket returns 1.

SERVER SOCKETS
     If the -server option is specified then  the  new  socket  will  be  a
     server for the port given  by  port.  Tcl  will  automatically  accept
     connections to the given port. For each connection Tcl will  create  a
     new channel that may be used to communicate with the client. Tcl  then
     invokes command with three additional arguments: the name of  the  new
     channel, the address, in network address  notation,  of  the  client's
     host, and the client's port number.
     The following additional option may also be specified before host:
          -myaddr addr
               Addr gives the domain-style name or numerical IP address  of
               the server-side network interface to use for the connection.
               This option may be useful if the server machine has multiple
               network interfaces. If the option is omitted then the server
               socket is bound to the special address INADDR_ANY so that it
               can accept connections from any interface.
     Server channels cannot be used for input or output; their sole use  is
     to accept new  client  connections.  The  channels  created  for  each
     incoming client connection are opened for input  and  output.  Closing
     the server channel shuts down the server so that  no  new  connections
     will be accepted; however, existing connections will be unaffected.
     Server sockets depend on the Tcl event mechanism to find out when  new
     connections are opened. If the application  doesn't  enter  the  event
     loop, for example by invoking the  vwait  command  or  calling  the  C
     procedure Tcl_DoOneEvent, then no connections will be accepted.


CONFIGURATION OPTIONS
     The fconfigure command can be used  to    query    several    readonly
     configuration options for socket channels:
          -error 
               This option gets the  current  error  status  of  the  given
               socket. This is useful when you  need  to  determine  if  an
               asynchronous connect operation succeeded. If  there  was  an
               error, the error message is returned. If there was no error,
               an empty string is returned.
          -sockname 
               This option returns a list of three elements,  the  address,
               the host name and the port number for  the  socket.  If  the
               host name cannot be computed, the    second    element    is
               identical to the address, the first element of the list.
          -peername 
               This option is not supported by server sockets.  For  client
               and accepted sockets, this option returns a  list  of  three
               elements; these are the address, the host name and the  port
               to which the peer socket is connected or bound. If the  host
               name cannot be computed, the second element of the  list  is
               identical to the address, its first element.

SEE ALSO
     flush, open, read

KEYWORDS 
     bind, channel, connection, domain name, host, network address, socket,
     tcp 






_________________________________________________________________

NAME
     source - Evaluate a file or resource as a Tcl script

SYNOPSIS
	source fileName
	source -rsrc resourceName ?fileName?
	source -rsrcid resourceId ?fileName?

_________________________________________________________________

DESCRIPTION 
     This command takes the contents of the specified file or resource  and
     passes it to the Tcl interpreter as a text script.  The  return  value
     from source is the return value of the last command  executed  in  the
     script. If an error occurs in evaluating the contents  of  the  script
     then the source command will return that error. If a return command is
     invoked from within the script then the remainder of the file will  be
     skipped and the source command will return normally  with  the  result
     from the return command.
     The end-of-file character for files is '\32' (^Z) for  all  platforms.
     The source  command  will  read  files  up  to  this  character.  This
     restriction does not exist for the read or gets commands, allowing for
     files containing code and data segments (scripted documents).  If  you
     require a ``^Z'' in code for string comparison, you can  use  ``\032''
     or ``\u001a'', which will be safely substituted by the Tcl interpreter
     into ``^Z''.
     The -rsrc and -rsrcid forms of this  command  are  only  available  on
     Macintosh computers. These versions of the command allow you to source
     a script from a TEXT resource. You may specify what TEXT  resource  to
     source by either name or id. By default Tcl searches all open resource
     files,  which  include  the  current  application  and  any  loaded  C
     extensions. Alternatively, you may specify the fileName where the TEXT
     resource can be found.


SEE ALSO
     file, cd

KEYWORDS 
     file, script






_________________________________________________________________

NAME
     split - Split a string into a proper Tcl list

SYNOPSIS
	split string ?splitChars?

_________________________________________________________________

DESCRIPTION 
     Returns a list created by splitting string at each character  that  is
     in the splitChars argument. Each  element  of  the  result  list  will
     consist of the characters from string that lie  between  instances  of
     the characters in splitChars. Empty list elements will be generated if
     string contains adjacent characters in splitChars, or if the first  or
     last character of string is in splitChars. If splitChars is  an  empty
     string then each character of string becomes a separate element of the
     result list. SplitChars defaults  to    the    standard    white-space
     characters. For example, split "comp.unix.misc" . returns  "comp  unix
     misc" and split "Hello world" {} returns "H e l l o { } w o r l d".


SEE ALSO
     join, list, string

KEYWORDS 
     list, split, string






_________________________________________________________________

NAME
     string - Manipulate strings

SYNOPSIS
	string option arg ?arg ...?

_________________________________________________________________

DESCRIPTION 
     Performs one of several string operations, depending  on  option.  The
     legal options (which may be abbreviated) are:
          string bytelength string
               Returns a decimal string giving the number of bytes used  to
               represent string in memory. Because UTF-8 uses one to  three
               bytes to represent Unicode characters, the byte length  will
               not be the same as the  character  length  in  general.  The
               cases where a script cares about the byte length  are  rare.
               In almost all  cases,  you  should  use  the  string  length
               operation. Refer to the  Tcl_NumUtfChars  manual  entry  for
               more details on the UTF-8 representation.
          string compare ?-nocase? ?-length int? string1 string2
               Perform a character-by-character comparison    of    strings
               string1 and string2. Returns  -1,  0,  or  1,  depending  on
               whether string1 is lexicographically less than, equal to, or
               greater than string2. If -length is specified, then only the
               first length characters  are  used  in  the  comparison.  If
               -length is negative, it is ignored. If -nocase is specified,
               then the strings are compared in a case-insensitive manner.
          string equal ?-nocase? ?-length int? string1 string2
               Perform a character-by-character comparison    of    strings
               string1 and string2. Returns 1 if string1  and  string2  are
               identical, or 0 when not. If -length is specified, then only
               the first length characters are used in the  comparison.  If
               -length is negative, it is ignored. If -nocase is specified,
               then the strings are compared in a case-insensitive manner.
          string first string1 string2 ?startIndex?
               Search string2 for a sequence  of  characters  that  exactly
               match the characters in string1. If found, return the  index
               of the first  character  in  the  first  such  match  within
               string2. If not found, return -1. If startIndex is specified
               (in any of the forms accepted by the index method), then the
               search is constrained to start with the character in string2
               specified by the index. For example,    string    first    a
               0a23456789abcdef 5  will  return  10,  but  string  first  a
               0123456789abcdef 11 will return -1.
          string index string charIndex
               Returns the charIndex'th character of the string argument. A
               charIndex of 0 corresponds to the  first  character  of  the
               string. charIndex may be specified as follows:
                    integer 
                         The char specified at this integral index
                    end 
                         The last char of the string.
                    end-integer 
                         The last char of the string  minus  the  specified
                         integer offset (e.g. end-1 would refer to the  "c"
                         in "abcd").
               If charIndex is less than 0 or greater than or equal to  the
               length of the string then an empty string is returned.
          string is class ?-strict? ?-failindex varname? string
               Returns 1 if string is  a  valid  member  of  the  specified
               character class, otherwise returns 0.    If    -strict    is
               specified, then an empty string  returns  0,  otherwise  and
               empty string will return 1 on any class.  If  -failindex  is
               specified, then if the function returns 0, the index in  the
               string where the class was no longer valid will be stored in
               the variable named varname. The varname will not be  set  if
               the function returns 1. The following character classes  are
               recognized (the class name can be abbreviated):
                    alnum 
                         Any Unicode alphabet or digit character.
                    alpha 
                         Any Unicode alphabet character.
                    ascii 
                         Any character with a value less than \u0080 (those
                         that are in the 7-bit ascii range).
                    boolean 
                         Any of the forms allowed to Tcl_GetBoolean.
                    control 
                         Any Unicode control character.
                    digit 
                         Any Unicode digit character.  Note    that    this
                         includes characters outside of the [0-9] range.
                    double 
                         Any of the valid forms for a double in  Tcl,  with
                         optional surrounding whitespace.  In    case    of
                         under/overflow in the value, 0 is returned and the
                         varname will contain -1.
                    false 
                         Any of the forms allowed to  Tcl_GetBoolean  where
                         the value is false.
                    graph 
                         Any Unicode printing character, except space.
                    integer 
                         Any of the valid forms for an integer in Tcl, with
                         optional surrounding whitespace.  In    case    of
                         under/overflow in the value, 0 is returned and the
                         varname will contain -1.
                    lower 
                         Any Unicode lower case alphabet character.
                    print 
                         Any Unicode printing character, including space.
                    punct 
                         Any Unicode punctuation character.
                    space 
                         Any Unicode space character.
                    true 
                         Any of the forms allowed to  Tcl_GetBoolean  where
                         the value is true.
                    upper 
                         Any upper case alphabet character in  the  Unicode
                         character set.
                    wordchar 
                         Any Unicode word   character.    That    is    any
                         alphanumeric character, and any Unicode  connector
                         punctuation characters (e.g. underscore).
                    xdigit 
                         Any hexadecimal digit character ([0-9A-Fa-f]).
               In the case of boolean, true and false, if the function will
               return 0, then the varname will always be set to 0,  due  to
               the varied nature of a valid boolean value.
          string last string1 string2 ?startIndex?
               Search string2 for a sequence  of  characters  that  exactly
               match the characters in string1. If found, return the  index
               of the  first  character  in  the  last  such  match  within
               string2. If there is no match, then return -1. If startIndex
               is specified (in any of the  forms  accepted  by  the  index
               method), then only the characters in string2  at  or  before
               the specified startIndex will be considered by  the  search.
               For example, string last a 0a23456789abcdef 15  will  return
               10, but string last a 0a23456789abcdef 9 will return 1.
          string length string
               Returns a decimal string giving the number of characters  in
               string. Note that this is not necessarily the  same  as  the
               number of bytes used to store the string.
          string map ?-nocase? charMap string
               Replaces characters in string based on the  key-value  pairs
               in charMap. charMap is a list of key value key value ...  as
               in the form returned by array get. Each instance of a key in
               the string will be replaced with its corresponding value. If
               -nocase is specified, then matching is done  without  regard
               to case differences. Both key  and  value  may  be  multiple
               characters. Replacement is done in an ordered manner, so the
               key appearing first in the list will be checked  first,  and
               so on. string is only iterated over  once,  so  earlier  key
               replacements will have no affect for later key matches.  For
               example, string map {abc 1 ab 2 a 3 1  0}  1abcaababcabababc
               will return the string 01321221.
          string match ?-nocase? pattern string
               See if pattern matches string; return 1 if it does, 0 if  it
               doesn't. If -nocase is specified, then the pattern  attempts
               to match against the string in a  case  insensitive  manner.
               For the  two  strings  to  match,  their  contents  must  be
               identical except that the following  special  sequences  may
               appear in pattern:
                    * 
                         Matches any  sequence  of  characters  in  string,
                         including a null string.
                    ? 
                         Matches any single character in string.
                    [chars] 
                         Matches any character in the set given  by  chars.
                         If a sequence of the form x-y  appears  in  chars,
                         then any character between  x  and  y,  inclusive,
                         will match. When used with -nocase, the end points
                         of the range are converted to  lower  case  first.
                         Whereas {[A-z]} matches    '_'    when    matching
                         case-sensitively ('_' falls between  the  'Z'  and
                         'a'), with -nocase this   is    considered    like
                         {[A-Za-z]} (and probably what  was  meant  in  the
                         first place).
                    \x 
                         Matches the single character x.  This  provides  a
                         way of avoiding the special interpretation of  the
                         characters *?[]\ in pattern.
          string range string first last
               Returns a  range  of  consecutive  characters  from  string,
               starting with the character whose index is first and  ending
               with the character whose index is last. An index of 0 refers
               to the first character of the string. first and last may  be
               specified as for the index method. If  first  is  less  than
               zero then it is treated as if it were zero, and if  last  is
               greater than or equal to the length of the string then it is
               treated as if it were end. If first  is  greater  than  last
               then an empty string is returned.
          string repeat string count
               Returns string repeated count number of times.
          string replace string first last ?newstring?
               Removes a  range  of  consecutive  characters  from  string,
               starting with the character whose index is first and  ending
               with the character whose index is last. An index of 0 refers
               to the first character of the string. First and last may  be
               specified as for the index  method.    If    newstring    is
               specified, then it is placed in the removed character range.
               If first is less than zero then it is treated as if it  were
               zero, and if last is greater than or equal to the length  of
               the string then it is treated as if it were end. If first is
               greater than last or the length of the  initial  string,  or
               last is less than 0, then the  initial  string  is  returned
               untouched. 
          string tolower string ?first? ?last?
               Returns a value equal to string except that  all  upper  (or
               title) case letters have been converted to  lower  case.  If
               first is specified, it refers to the first char index in the
               string to start modifying. If last is specified,  it  refers
               to the char index in the  string  to  stop  at  (inclusive).
               first and last may be specified as for the index method.
          string totitle string ?first? ?last?
               Returns a value  equal  to  string  except  that  the  first
               character in string is converted to its Unicode  title  case
               variant (or upper case if there is no  title  case  variant)
               and the rest of the string is converted to  lower  case.  If
               first is specified, it refers to the first char index in the
               string to start modifying. If last is specified,  it  refers
               to the char index in the  string  to  stop  at  (inclusive).
               first and last may be specified as for the index method.
          string toupper string ?first? ?last?
               Returns a value equal to string except that  all  lower  (or
               title) case letters have been converted to  upper  case.  If
               first is specified, it refers to the first char index in the
               string to start modifying. If last is specified,  it  refers
               to the char index in the  string  to  stop  at  (inclusive).
               first and last may be specified as for the index method.
          string trim string ?chars?
               Returns a value equal to string except that any  leading  or
               trailing characters from the set given by chars are removed.
               If chars is  not  specified  then  white  space  is  removed
               (spaces, tabs, newlines, and carriage returns).
          string trimleft string ?chars?
               Returns a value equal to  string  except  that  any  leading
               characters from the set given by chars are removed. If chars
               is not specified then white space is removed (spaces,  tabs,
               newlines, and carriage returns).
          string trimright string ?chars?
               Returns a value equal to string  except  that  any  trailing
               characters from the set given by chars are removed. If chars
               is not specified then white space is removed (spaces,  tabs,
               newlines, and carriage returns).
          string wordend string charIndex
               Returns the index of the character just after the  last  one
               in  the  word  containing  character  charIndex  of  string.
               charIndex may be specified as for the index method.  A  word
               is considered to be any  contiguous  range  of  alphanumeric
               (Unicode letters or decimal digits) or  underscore  (Unicode
               connector punctuation) characters, or any  single  character
               other than these.
          string wordstart string charIndex
               Returns the  index  of  the  first  character  in  the  word
               containing character charIndex of string. charIndex  may  be
               specified as for the index method. A word is  considered  to
               be any contiguous range of alphanumeric (Unicode letters  or
               decimal digits)    or    underscore    (Unicode    connector
               punctuation) characters, or any single character other  than
               these. 

SEE ALSO
     expr, list

KEYWORDS 
     case conversion, compare, index, match, pattern, string, word,  equal,
     ctype 






_________________________________________________________________

NAME
     subst - Perform backslash, command, and variable substitutions

SYNOPSIS
	subst ?-nobackslashes? ?-nocommands? ?-novariables? string

_________________________________________________________________

DESCRIPTION 
     This command performs variable substitutions,  command  substitutions,
     and backslash substitutions on its string  argument  and  returns  the
     fully-substituted result. The substitutions are performed  in  exactly
     the same way as for Tcl commands. As a result, the string argument  is
     actually substituted twice, once  by  the  Tcl  parser  in  the  usual
     fashion for Tcl commands, and again by the subst command.
     If  any  of  the  -nobackslashes,  -nocommands,  or  -novariables  are
     specified, then the corresponding substitutions are not performed. For
     example, if -nocommands  is  specified,  no  command  substitution  is
     performed: open and close brackets are treated as ordinary  characters
     with no special interpretation.
     Note: when it performs its substitutions,  subst  does  not  give  any
     special treatment to double quotes or curly braces. For  example,  the
     script set a 44 subst {xyz  {$a}}  returns  ``xyz  {44}'',  not  ``xyz
     {$a}''. 


SEE ALSO
     eval 

KEYWORDS 
     backslash substitution, command substitution, variable substitution






_________________________________________________________________

NAME
     switch - Evaluate one of several scripts, depending on a given value

SYNOPSIS
	switch ?options? string pattern body ?pattern body ...?
	switch ?options? string {pattern body ?pattern body ...?}

_________________________________________________________________

DESCRIPTION 
     The switch command matches its string argument  against  each  of  the
     pattern arguments in order. As soon as it finds a pattern that matches
     string  it  evaluates  the  following  body  argument  by  passing  it
     recursively to the Tcl interpreter and  returns  the  result  of  that
     evaluation. If the last pattern argument is default  then  it  matches
     anything. If no pattern argument matches  string  and  no  default  is
     given, then the switch command returns an empty string.
     If the initial arguments to switch start with - then they are  treated
     as options. The following options are currently supported:
          -exact 
               Use exact matching when comparing string to a pattern.  This
               is the default.
          -glob 
               When matching string to the   patterns,    use    glob-style
               matching (i.e. the same as implemented by the  string  match
               command). 
          -regexp 
               When matching string to the patterns, use regular expression
               matching (as described in the re_syntax reference page).
          -- 
               Marks the end of options. The argument  following  this  one
               will be treated as string even if it starts with a -.
     Two syntaxes are provided for the  pattern  and  body  arguments.  The
     first uses a separate argument for each of the patterns and  commands;
     this form is convenient if substitutions are desired on  some  of  the
     patterns or commands. The second form places all of the  patterns  and
     commands together into a  single  argument;  the  argument  must  have
     proper list structure,  with  the  elements  of  the  list  being  the
     patterns and commands. The second form  makes  it  easy  to  construct
     multi-line switch commands, since the braces  around  the  whole  list
     make it unnecessary to include a backslash at the end  of  each  line.
     Since the pattern arguments are in  braces  in  the  second  form,  no
     command or variable substitutions are performed on  them;  this  makes
     the behavior of the second form different than the first form in  some
     cases. 
     If a body is specified as ``-'' it means that the body  for  the  next
     pattern should also be used as the body for this pattern (if the  next
     pattern also has a body of ``-'' then the body after that is used, and
     so on). This feature makes it possible to share a  single  body  among
     several patterns.
     Beware of how you place comments in switch commands.  Comments  should
     only be placed inside the execution body of one of the  patterns,  and
     not intermingled with the patterns.
     Below are some examples of switch commands: switch abc a -  b  {format
     1} abc {format 2} default {format 3} will  return  2,  switch  -regexp
     aaab { ^a.*b$ - b {format 1} a* {format 2} default {format 3}  }  will
     return 1, and switch xyz { a - b { # Correct Comment Placement  format
     1 } a* {format 2} default {format 3} } will return 3.


SEE ALSO
     for, if, regexp

KEYWORDS 
     switch, match, regular expression






_________________________________________________________________

NAME
     Tcl - Summary of Tcl language syntax.

_________________________________________________________________

DESCRIPTION 
     The following rules  define  the  syntax  and  semantics  of  the  Tcl
     language: 
          [1] 
               A Tcl script is a string containing one  or  more  commands.
               Semi-colons  and  newlines  are  command  separators  unless
               quoted  as  described  below.  Close  brackets  are  command
               terminators during command substitution (see  below)  unless
               quoted. 
          [2] 
               A  command  is  evaluated  in  two  steps.  First,  the  Tcl
               interpreter breaks  the  command  into  words  and  performs
               substitutions as described below.  These  substitutions  are
               performed in the same way for all commands. The  first  word
               is used to locate a  command  procedure  to  carry  out  the
               command, then all of the words of the command are passed  to
               the command procedure. The  command  procedure  is  free  to
               interpret each of its words in any way it likes, such as  an
               integer, variable  name,  list,  or  Tcl  script.  Different
               commands interpret their words differently.
          [3] 
               Words of a command are separated by white space (except  for
               newlines, which are command separators).
          [4] 
               If the first character of a  word  is  double-quote  (``"'')
               then  the  word  is  terminated  by  the  next  double-quote
               character. If semi-colons, close brackets,  or  white  space
               characters (including newlines) appear  between  the  quotes
               then they are treated as ordinary characters and included in
               the word. Command substitution, variable  substitution,  and
               backslash  substitution  are  performed  on  the  characters
               between the quotes as described below. The double-quotes are
               not retained as part of the word.
          [5] 
               If the first character of a word is an  open  brace  (``{'')
               then the word is terminated  by  the  matching  close  brace
               (``}''). Braces nest within the word:  for  each  additional
               open brace there must be an additional close brace (however,
               if an open brace or close brace within the  word  is  quoted
               with a backslash then it is  not  counted  in  locating  the
               matching close brace). No substitutions are performed on the
               characters between the braces except  for  backslash-newline
               substitutions described below, nor do semi-colons, newlines,
               close brackets, or white  space    receive    any    special
               interpretation. The word will consist   of    exactly    the
               characters between  the  outer  braces,  not  including  the
               braces themselves.
          [6] 
               If a word contains an open bracket (``['') then Tcl performs
               command substitution. To do this it    invokes    the    Tcl
               interpreter recursively to process the characters  following
               the open bracket as a Tcl script. The script may contain any
               number of commands and must be terminated by a close bracket
               (``]''). The result of the script (i.e. the  result  of  its
               last command) is substituted into the word in place  of  the
               brackets and all of the characters between them.  There  may
               be any number of command substitutions  in  a  single  word.
               Command substitution is not performed on words  enclosed  in
               braces. 
          [7] 
               If a word contains a dollar-sign (``$'') then  Tcl  performs
               variable substitution: the  dollar-sign  and  the  following
               characters are replaced in  the  word  by  the  value  of  a
               variable. Variable substitution may take    any    of    the
               following forms:
                    $name 
                         Name is the name of a scalar variable; the name is
                         terminated by any character that isn't  a  letter,
                         digit, or underscore.
                    $name(index) 
                         Name gives the name of an array variable and index
                         gives the name of an element  within  that  array.
                         Name must contain only  letters,    digits,    and
                         underscores. Command    substitutions,    variable
                         substitutions,  and  backslash  substitutions  are
                         performed on the characters of index.
                    ${name} 
                         Name is the name of  a  scalar  variable.  It  may
                         contain any characters whatsoever except for close
                         braces. 
               There may be any  number  of  variable  substitutions  in  a
               single word. Variable substitution is not performed on words
               enclosed in braces.
          [8] 
               If a backslash (``\'') appears within a word then  backslash
               substitution occurs. In all cases but those described  below
               the backslash is dropped  and  the  following  character  is
               treated as an ordinary character and included in  the  word.
               This allows characters such as    double    quotes,    close
               brackets, and dollar signs to be included in  words  without
               triggering special processing. The following table lists the
               backslash sequences that are handled specially,  along  with
               the value that replaces each sequence.
                    \a 
                         Audible alert (bell) (0x7).
                    \b 
                         Backspace (0x8).
                    \f 
                         Form feed (0xc).
                    \n 
                         Newline (0xa).
                    \r 
                         Carriage-return (0xd).
                    \t 
                         Tab (0x9).
                    \v 
                         Vertical tab (0xb).
                    \<newline>whiteSpace 
                         A single space character replaces  the  backslash,
                         newline, and all spaces and   tabs    after    the
                         newline. This backslash sequence is unique in that
                         it is replaced in a separate pre-pass  before  the
                         command is actually parsed.  This  means  that  it
                         will be  replaced  even  when  it  occurs  between
                         braces, and the resulting space will be treated as
                         a word separator if it isn't in braces or quotes.
                    \\ 
                         Backslash (``\'').
                    \ooo 
                         The digits ooo (one, two, or three of  them)  give
                         an eight-bit octal value for the Unicode character
                         that will be  inserted.  The  upper  bits  of  the
                         Unicode character will be 0.
                    \xhh 
                         The hexadecimal digits hh  give    an    eight-bit
                         hexadecimal value for the Unicode  character  that
                         will be inserted. Any number of hexadecimal digits
                         may be present; however, all but the last two  are
                         ignored (the result  is    always    a    one-byte
                         quantity). The upper bits of the Unicode character
                         will be 0.
                    \uhhhh 
                         The hexadecimal digits hhhh (one, two,  three,  or
                         four of them) give a sixteen-bit hexadecimal value
                         for the Unicode character that will be inserted.
               Backslash substitution is not performed on words enclosed in
               braces, except for backslash-newline as described above.
          [9] 
               If a hash character (``#'') appears at a point where Tcl  is
               expecting the  first  character  of  the  first  word  of  a
               command, then the hash character  and  the  characters  that
               follow it, up through the next newline,  are  treated  as  a
               comment and ignored. The comment    character    only    has
               significance when it appears at the beginning of a command.
          [10] 
               Each character is processed exactly once    by    the    Tcl
               interpreter as part of creating the words of a command.  For
               example, if variable substitution  occurs  then  no  further
               substitutions are performed on the value  of  the  variable;
               the value is inserted into the  word  verbatim.  If  command
               substitution occurs then the  nested  command  is  processed
               entirely by the recursive call to the  Tcl  interpreter;  no
               substitutions are performed before making the recursive call
               and no additional substitutions are performed on the  result
               of the nested script.
          [11] 
               Substitutions  do  not  affect  the  word  boundaries  of  a
               command.  For  example,  during  variable  substitution  the
               entire value of the variable becomes part of a single  word,
               even if the variable's value contains spaces.





_________________________________________________________________

NAME
     tclvars - Variables used by Tcl

_________________________________________________________________

DESCRIPTION 
     The following global variables are created and  managed  automatically
     by the Tcl library. Except where noted below, these  variables  should
     normally be treated as read-only by application-specific code  and  by
     users. 
          env 
               This variable  is  maintained  by  Tcl  as  an  array  whose
               elements are the  environment  variables  for  the  process.
               Reading an element will  return    the    value    of    the
               corresponding environment variable. Setting  an  element  of
               the array will modify the corresponding environment variable
               or create a new one if it doesn't already  exist.  Unsetting
               an element of env will remove the corresponding  environment
               variable. Changes to the env  array    will    affect    the
               environment passed to children by commands like exec. If the
               entire env array is unset then Tcl will stop monitoring  env
               accesses and will not update environment variables.
                         Under Windows, the environment variables PATH  and
                         COMSPEC in any  capitalization    are    converted
                         automatically to upper  case.  For  instance,  the
                         PATH variable could be exported by  the  operating
                         system  as  ``path'',  ``Path'',  ``PaTh'',  etc.,
                         causing otherwise  simple  Tcl  code  to  have  to
                         support many special cases. All other  environment
                         variables inherited by Tcl are left unmodified.

                         On the  Macintosh,  the  environment  variable  is
                         constructed by Tcl as  no    global    environment
                         variable exists. The  environment  variables  that
                         are created for Tcl include:
                              LOGIN 
                                   This  holds  the  Chooser  name  of  the
                                   Macintosh. 
                              USER 
                                   This also holds the Chooser name of  the
                                   Macintosh. 
                              SYS_FOLDER 
                                   The path to the system directory.
                              APPLE_M_FOLDER 
                                   The path to the Apple Menu directory.
                              CP_FOLDER 
                                   The path  to    the    control    panels
                                   directory. 
                              DESK_FOLDER 
                                   The path to the desk top directory.
                              EXT_FOLDER 
                                   The path to  the    system    extensions
                                   directory. 
                              PREF_FOLDER 
                                   The path to the preferences directory.
                              PRINT_MON_FOLDER 
                                   The path to the print monitor directory.
                                    
                              SHARED_TRASH_FOLDER 
                                   The path to the network trash directory.
                                    
                              TRASH_FOLDER 
                                   The path to the trash directory.
                              START_UP_FOLDER 
                                   The path to the start up directory.
                              PWD 
                                   The path to  the  application's  default
                                   directory. 
                         You can also  create    your    own    environment
                         variables for the  Macintosh.  A  file  named  Tcl
                         Environment Variables may be   placed    in    the
                         preferences folder in the Mac system folder.  Each
                         line of this file should   be    of    the    form
                         VAR_NAME=var_data. 
                         The  last  alternative  is  to  place  environment
                         variables in a  'STR#'    resource    named    Tcl
                         Environment Variables of the application. This  is
                         considered a little more ``Mac like'' than a  Unix
                         style Environment Variable file. Each entry in the
                         'STR#' resource has the same format as above.  The
                         source code file    tclMacEnv.c    contains    the
                         implementation of the env  mechanisms.  This  file
                         contains many #define's that  allow  customization
                         of the env mechanisms  to  fit  your  applications
                         needs. 

          errorCode 
               After an error has occurred, this variable will  be  set  to
               hold additional information about the error in a  form  that
               is easy to process with programs. errorCode  consists  of  a
               Tcl list with one or more elements. The first element of the
               list identifies a general class of  errors,  and  determines
               the format of the rest of the list.  The  following  formats
               for errorCode are used by  the    Tcl    core;    individual
               applications may define additional formats.
                    ARITH code msg
                         This format  is  used  when  an  arithmetic  error
                         occurs (e.g. an attempt to divide by zero  in  the
                         expr command). Code identifies the  precise  error
                         and msg provides a human-readable  description  of
                         the error. Code will be  either  DIVZERO  (for  an
                         attempt to divide by zero), DOMAIN (if an argument
                         is outside the  domain  of  a  function,  such  as
                         acos(-3)), IOVERFLOW (for    integer    overflow),
                         OVERFLOW (for a floating-point    overflow),    or
                         UNKNOWN (if the  cause  of  the  error  cannot  be
                         determined). 
                    CHILDKILLED pid sigName msg
                         This format is used when a child process has  been
                         killed because of a signal. The second element  of
                         errorCode will be  the  process's  identifier  (in
                         decimal). The third element will be  the  symbolic
                         name of the signal  that  caused  the  process  to
                         terminate; it will be one of the  names  from  the
                         include file signal.h, such as SIGPIPE. The fourth
                         element will be  a  short  human-readable  message
                         describing the signal, such  as  ``write  on  pipe
                         with no readers'' for SIGPIPE.
                    CHILDSTATUS pid code
                         This format is  used  when  a  child  process  has
                         exited with a non-zero  exit  status.  The  second
                         element of errorCode will   be    the    process's
                         identifier (in decimal) and the third element will
                         be the exit code returned by the process (also  in
                         decimal). 
                    CHILDSUSP pid sigName msg
                         This format is used when a child process has  been
                         suspended because of a signal. The second  element
                         of errorCode will be the process's identifier,  in
                         decimal. The third element will  be  the  symbolic
                         name of the signal  that  caused  the  process  to
                         suspend; this will be one of the  names  from  the
                         include file signal.h, such as SIGTTIN. The fourth
                         element will be  a  short  human-readable  message
                         describing the signal, such  as  ``background  tty
                         read'' for SIGTTIN.
                    NONE 
                         This format is used for errors where no additional
                         information is available for an error besides  the
                         message returned with the error.  In  these  cases
                         errorCode will consist  of  a  list  containing  a
                         single element whose contents are NONE.
                    POSIX errName msg
                         If the first element of errorCode is  POSIX,  then
                         the error occurred during a POSIX kernel call. The
                         second  element  of  the  list  will  contain  the
                         symbolic name of the error that occurred, such  as
                         ENOENT; this will be one of the values defined  in
                         the include file errno.h. The third element of the
                         list  will    be    a    human-readable    message
                         corresponding to errName, such as ``no  such  file
                         or directory'' for the ENOENT case.
               To set errorCode, applications should use library procedures
               such as Tcl_SetErrorCode and  Tcl_PosixError,  or  they  may
               invoke the error command. If one  of  these  methods  hasn't
               been used, then the Tcl interpreter will reset the  variable
               to NONE after the next error.
          errorInfo 
               After an error has occurred, this string will contain one or
               more lines identifying the Tcl commands and procedures  that
               were being executed when the most recent error occurred. Its
               contents take the form of a stack trace showing the  various
               nested Tcl commands that had been invoked at the time of the
               error. 
          tcl_library 
               This variable holds the name of a directory  containing  the
               system library of  Tcl  scripts,  such  as  those  used  for
               auto-loading. The value of this variable is returned by  the
               info library command.  See  the  library  manual  entry  for
               details  of  the  facilities  provided  by  the  Tcl  script
               library. Normally each application or package will have  its
               own application-specific script library in addition  to  the
               Tcl script library; each application  should  set  a  global
               variable with a name like $app_library  (where  app  is  the
               application's name) to hold the network file name  for  that
               application's library directory. The  initial    value    of
               tcl_library  is  set  when  an  interpreter  is  created  by
               searching several different directories until one  is  found
               that contains an appropriate  Tcl  startup  script.  If  the
               TCL_LIBRARY environment variable exists, then the  directory
               it names is checked  first.  If  TCL_LIBRARY  isn't  set  or
               doesn't refer to an appropriate directory, then  Tcl  checks
               several other directories based  on  a  compiled-in  default
               location, the location of the    binary    containing    the
               application, and the current working directory.
          tcl_patchLevel 
               When an interpreter is created Tcl initializes this variable
               to hold a string giving the current  patch  level  for  Tcl,
               such as 7.3p2 for  Tcl  7.3  with  the  first  two  official
               patches, or 7.4b4 for the fourth beta release  of  Tcl  7.4.
               The value of this variable is  returned    by    the    info
               patchlevel command.
          tcl_pkgPath 
               This variable holds a list of directories  indicating  where
               packages are normally installed. It is not used on  Windows.
               It typically contains either  one  or  two  entries;  if  it
               contains two entries, the first is normally a directory  for
               platform-dependent packages (e.g., shared library  binaries)
               and the    second    is    normally    a    directory    for
               platform-independent packages    (e.g.,    script    files).
               Typically a package is installed as a subdirectory of one of
               the entries in $tcl_pkgPath. The directories in $tcl_pkgPath
               are included by default in the auto_path variable,  so  they
               and their immediate   subdirectories    are    automatically
               searched for packages during package require commands. Note:
               tcl_pkgPath it not intended to   be    modified    by    the
               application. Its value is added  to  auto_path  at  startup;
               changes to tcl_pkgPath are not reflected  in  auto_path.  If
               you want Tcl to search additional directories  for  packages
               you should add the names of those directories to  auto_path,
               not tcl_pkgPath.
          tcl_platform 
               This is an associative array    whose    elements    contain
               information about the platform on which the  application  is
               running, such as the  name  of  the  operating  system,  its
               current release number, and the machine's  instruction  set.
               The elements listed below will always be defined,  but  they
               may have empty strings as values if  Tcl  couldn't  retrieve
               any relevant information. In  addition,    extensions    and
               applications may add additional values  to  the  array.  The
               predefined elements are:





                    byteOrder 
                         The native byte  order  of  this  machine:  either
                         littleEndian or bigEndian.
                    debug 
                         If this variable exists, then the interpreter  was
                         compiled  with  debugging  symbols  enabled.  This
                         varible will only exist on  Windows  so  extension
                         writers can specify which    package    to    load
                         depending  on  the  C  run-time  library  that  is
                         loaded. 
                    machine 
                         The instruction set executed by this machine, such
                         as intel, PPC, 68k, or sun4m.  On  UNIX  machines,
                         this is the value returned by uname -m.
                    os 
                         The name of the operating system running  on  this
                         machine, such as Windows 95, Windows NT, MacOS, or
                         SunOS. On UNIX machines, this   is    the    value
                         returned by uname -s. On Windows  95  and  Windows
                         98, the value  returned  will  be  Windows  95  to
                         provide better backwards compatibility to  Windows
                         95; to distinguish  between  the  two,  check  the
                         osVersion. 
                    osVersion 
                         The version number for  the    operating    system
                         running on this machine. On UNIX machines, this is
                         the value returned by uname -r. On Windows 95, the
                         version will be 4.0; on Windows  98,  the  version
                         will be 4.10.
                    platform 
                         Either windows,  macintosh,    or    unix.    This
                         identifies the general  operating  environment  of
                         the machine.
                    threaded 
                         If this variable exists, then the interpreter  was
                         compiled with threads enabled.
                    user 
                         This identifies the  current  user  based  on  the
                         login information available on the platform.  This
                         comes from the USER   or    LOGNAME    environment
                         variable on Unix, and the value  from  GetUserName
                         on Windows and Macintosh.
          tcl_precision 
               This variable controls the number of digits to generate when
               converting floating-point values to strings. It defaults  to
               12. 17 digits is ``perfect'' for IEEE floating-point in that
               it allows double-precision values to be converted to strings
               and back to binary with no  loss  of  information.  However,
               using  17  digits  prevents  any  rounding,  which  produces
               longer,  less  intuitive  results.  For  example,  expr  1.4
               returns 1.3999999999999999 with tcl_precision set to 17, vs.
               1.4 if tcl_precision is 12.
                         All interpreters  in  a  process  share  a  single
                         tcl_precision value:   changing    it    in    one
                         interpreter will affect all other interpreters  as
                         well. However, safe interpreters are  not  allowed
                         to modify the variable.

          tcl_rcFileName 
               This variable is used during initialization to indicate  the
               name of a user-specific  startup  file.  If  it  is  set  by
               application-specific initialization, then  the  Tcl  startup
               code will check for the existence of this file and source it
               if it exists. For example, for wish the variable is  set  to
               ~/.wishrc for Unix and ~/wishrc.tcl for Windows.
          tcl_rcRsrcName 
               This  variable  is  only  used  on  Macintosh  systems.  The
               variable is used during initialization to indicate the  name
               of a user-specific TEXT resource located in the  application
               or extension resource  forks.    If    it    is    set    by
               application-specific initialization, then  the  Tcl  startup
               code will check for  the  existence  of  this  resource  and
               source it if it exists.  For  example,  the  Macintosh  wish
               application has the variable is set to tclshrc.
          tcl_traceCompile 
               The value of this variable can be set to  control  how  much
               tracing information    is    displayed    during    bytecode
               compilation. By default, tcl_traceCompile  is  zero  and  no
               information is  displayed.  Setting  tcl_traceCompile  to  1
               generates a one line summary in stdout whenever a  procedure
               or top level command is compiled. Setting it to 2  generates
               a detailed listing in stdout of  the  bytecode  instructions
               emitted during every compilation. This variable is useful in
               tracking down suspected problems with the Tcl  compiler.  It
               is also occasionally useful when converting existing code to
               use Tcl8.0.
          tcl_traceExec 
               The value of this variable can be set to  control  how  much
               tracing information is displayed during bytecode  execution.
               By default, tcl_traceExec is  zero  and  no  information  is
               displayed. Setting tcl_traceExec to 1 generates a  one  line
               trace in stdout on each call to a Tcl procedure. Setting  it
               to 2 generates a line of output whenever any Tcl command  is
               invoked that contains  the  name  of  the  command  and  its
               arguments. Setting it to 3 produces a detailed trace showing
               the result of executing each bytecode instruction. Note that
               when tcl_traceExec is 2 or 3, commands such as set and  incr
               that have been entirely replaced by a sequence  of  bytecode
               instructions are not shown. Setting this variable is  useful
               in  tracking  down  suspected  problems  with  the  bytecode
               compiler and interpreter. It  is  also  occasionally  useful
               when converting code to use Tcl8.0.
          tcl_wordchars 
               The value of this variable is a regular expression that  can
               be set to control what are considered  ``word''  characters,
               for instances like selecting a word  by  double-clicking  in
               text in  Tk.  It  is  platform  dependent.  On  Windows,  it
               defaults  to  \S,  meaning  anything  but  a  Unicode  space
               character. Otherwise it defaults to \w, which is any Unicode
               word character (number, letter, or underscore).
          tcl_nonwordchars 
               The value of this variable is a regular expression that  can
               be set to control  what    are    considered    ``non-word''
               characters, for instances like  selecting    a    word    by
               double-clicking in text in Tk. It is platform dependent.  On
               Windows, it  defaults  to  \s,  meaning  any  Unicode  space
               character. Otherwise it defaults to \W,  which  is  anything
               but a Unicode word    character    (number,    letter,    or
               underscore). 
          tcl_version 
               When an interpreter is created Tcl initializes this variable
               to hold the version number for this version of  Tcl  in  the
               form x.y. Changes to x represent major changes with probable
               incompatibilities and changes  to    y    represent    small
               enhancements and  bug    fixes    that    retain    backward
               compatibility. The value of this variable is returned by the
               info tclversion command.

SEE ALSO
     eval 

KEYWORDS 
     arithmetic, bytecode, compiler, error, environment, POSIX,  precision,
     subprocess, variables






_________________________________________________________________

NAME
     tell - Return current access position for an open channel

SYNOPSIS
	tell channelId

_________________________________________________________________

DESCRIPTION 
     Returns an integer  string  giving  the  current  access  position  in
     channelId. This value returned is a byte offset that can be passed  to
     seek in order to set the channel to a particular position.  Note  that
     this value is in terms of bytes, not characters like read.  The  value
     returned is -1 for channels that do not support seeking.


SEE ALSO
     file, open, close, gets, seek

KEYWORDS 
     access position, channel, seeking






_________________________________________________________________

NAME
     time - Time the execution of a script

SYNOPSIS
	time script ?count?

_________________________________________________________________

DESCRIPTION 
     This command will call the Tcl interpreter  count  times  to  evaluate
     script (or once if count isn't  specified).  It  will  then  return  a
     string of the form 503 microseconds per iteration which indicates  the
     average amount of time required per iteration, in  microseconds.  Time
     is measured in elapsed time, not CPU time.


SEE ALSO
     clock 

KEYWORDS 
     script, time






_________________________________________________________________

NAME
     trace - Monitor variable accesses and command usages

SYNOPSIS
	trace option ?arg arg ...?

_________________________________________________________________

DESCRIPTION 
     This command causes Tcl  commands  to  be  executed  whenever  certain
     operations are invoked. The legal option's (which may be  abbreviated)
     are: 
          trace add type name ops ?args?
               Where type is command, or variable.
                    trace add command name ops command
                         Arrange for command to  be    executed    whenever
                         command name is modified in one of the ways  given
                         by the list ops. Name will be resolved  using  the
                         usual namespace  resolution    rules    used    by
                         procedures. If the  command  does  not  exist,  an
                         error will be thrown.
                         Ops indicates which operations  are  of  interest,
                         and is a list of one  or  more  of  the  following
                         items: 
                              rename 
                                   Invoke command whenever the  command  is
                                   renamed. Note that renaming to the empty
                                   string is considered deletion, and  will
                                   not be traced with 'rename'.
                              delete 
                                   Invoke command when the    command    is
                                   deleted. Commands   can    be    deleted
                                   explicitly by using the  rename  command
                                   to rename the command  to    an    empty
                                   string. Commands are also  deleted  when
                                   the interpreter is deleted,  but  traces
                                   will not be invoked because there is  no
                                   interpreter in which to execute them.
                         When  the  trace  triggers,  three  arguments  are
                         appended to command so that the actual command  is
                         as follows: command oldName newName op OldName and
                         newName give the traced  command's  current  (old)
                         namename, and  the  name  to  which  it  is  being
                         renamed (the empty string if this  is  a  'delete'
                         operation). Op indicates what operation  is  being
                         performed on the variable, and is one of rename or
                         delete  as  defined  above.  The  trace  operation
                         cannot be  used  to  stop  a  command  from  being
                         deleted. Tcl will always remove the  command  once
                         the  trace  is  complete.  Recursive  renaming  or
                         deleting will not cause further traces of the same
                         type to be evaluated,  so  a  delete  trace  which
                         itself deletes the  command,  or  a  rename  trace
                         which itself renames the command  will  not  cause
                         further trace evaluations to occur.
                    trace add variable name ops command
                         Arrange for command to  be    executed    whenever
                         variable name is accessed in one of the ways given
                         by the list  ops.  Name  may  refer  to  a  normal
                         variable, an element of an array, or to  an  array
                         as a whole (i.e. name may be just the name  of  an
                         array,  with  no  parenthesized  index).  If  name
                         refers to a whole array, then command  is  invoked
                         whenever any element of the array is  manipulated.
                         If the variable does not exist, it will be created
                         but will not be given  a  value,  so  it  will  be
                         visible to namespace which  queries,  but  not  to
                         info exists queries.
                         Ops indicates which operations  are  of  interest,
                         and is a list of one  or  more  of  the  following
                         items: 
                              array 
                                   Invoke command whenever the variable  is
                                   accessed or modified via    the    array
                                   command, provided that  name  is  not  a
                                   scalar variable at  the  time  that  the
                                   array command is invoked. If name  is  a
                                   scalar  variable,  the  access  via  the
                                   array command will not    trigger    the
                                   trace. read Invoke command whenever  the
                                   variable is read.
                              write 
                                   Invoke command whenever the variable  is
                                   written. 
                              unset 
                                   Invoke command whenever the variable  is
                                   unset. Variables can be unset explicitly
                                   with the unset  command,  or  implicitly
                                   when procedures  return  (all  of  their
                                   local variables  are  unset).  Variables
                                   are also  unset  when  interpreters  are
                                   deleted, but traces will not be  invoked
                                   because there is no interpreter in which
                                   to execute them.
                                    
                         When  the  trace  triggers,  three  arguments  are
                         appended to command so that the actual command  is
                         as follows: command name1 name2 op Name1 and name2
                         give the name(s) for the variable being  accessed:
                         if the variable is a scalar then name1  gives  the
                         variable's name and name2 is an empty  string;  if
                         the variable is an array element then name1  gives
                         the name of the array and name2  gives  the  index
                         into the  array;  if  an  entire  array  is  being
                         deleted  and  the  trace  was  registered  on  the
                         overall array, rather than a single element,  then
                         name1 gives the array name and name2 is  an  empty
                         string. Name1 and name2 are  not  necessarily  the
                         same as  the  name  used  in  the  trace  variable
                         command: the upvar command allows a  procedure  to
                         reference a variable under a  different  name.  Op
                         indicates what operation is being performed on the
                         variable, and is one of read, write, or  unset  as
                         defined above.
                         Command executes in the same context as  the  code
                         that invoked the traced operation: if the variable
                         was accessed as part  of  a  Tcl  procedure,  then
                         command will have access to   the    same    local
                         variables as code in the procedure.  This  context
                         may be different than the  context  in  which  the
                         trace was created. If command invokes a  procedure
                         (which it normally does) then the  procedure  will
                         have to use upvar  or  uplevel  if  it  wishes  to
                         access the traced variable. Note also  that  name1
                         may not necessarily be the same as the  name  used
                         to set the trace on the variable; differences  can
                         occur if the access is  made  through  a  variable
                         defined with the upvar command.
                         For read and write traces, command can modify  the
                         variable  to  affect  the  result  of  the  traced
                         operation. If command  modifies  the  value  of  a
                         variable during a read or write  trace,  then  the
                         new value will be returned as the  result  of  the
                         traced operation. The return value from command is
                         ignored except that if it returns an error of  any
                         sort then the traced  operation  also  returns  an
                         error with the same error message returned by  the
                         trace command  (this  mechanism  can  be  used  to
                         implement read-only variables, for  example).  For
                         write traces, command is   invoked    after    the
                         variable's value has been changed; it can write  a
                         new  value  into  the  variable  to  override  the
                         original value specified in the  write  operation.
                         To implement  read-only  variables,  command  will
                         have to restore the old value of the variable.
                         While command is executing during a read or  write
                         trace, traces  on  the  variable  are  temporarily
                         disabled. This means that reads and writes invoked
                         by command will occur directly,  without  invoking
                         command (or any other traces) again.  However,  if
                         command unsets the variable then unset traces will
                         be invoked.
                         When an unset trace is invoked, the  variable  has
                         already been deleted: it will   appear    to    be
                         undefined with  no  traces.  If  an  unset  occurs
                         because of a procedure return, then the trace will
                         be invoked in the variable    context    of    the
                         procedure being returned to: the  stack  frame  of
                         the returning  procedure  will  no  longer  exist.
                         Traces are not disabled during unset traces, so if
                         an unset trace command creates  a  new  trace  and
                         accesses the variable, the trace will be  invoked.
                         Any errors in unset traces are ignored.
                         If there are multiple traces on  a  variable  they
                         are invoked  in  order  of  creation,  most-recent
                         first. If one trace  returns  an  error,  then  no
                         further traces are invoked for the variable. If an
                         array element has a trace set, and there is also a
                         trace set on the array as a whole,  the  trace  on
                         the overall array is invoked before the one on the
                         element. 
                         Once created, the trace remains in  effect  either
                         until the trace is removed with the  trace  remove
                         variable command described  below,    until    the
                         variable is unset, or  until  the  interpreter  is
                         deleted. Unsetting an element of array will remove
                         any traces on that element, but  will  not  remove
                         traces on the overall array.
                         This command returns an empty string.
          trace remove type name opList command
               Where type is either command or variable.
                    trace remove command name opList command
                         If there is a trace set on command name  with  the
                         operations and command given   by    opList    and
                         command,  then  the  trace  is  removed,  so  that
                         command will never again be  invoked.  Returns  an
                         empty string. If name doesn't exist,  the  command
                         will throw an error.
                    trace remove variable name opList command
                         If there is a trace set on variable name with  the
                         operations and command given   by    opList    and
                         command,  then  the  trace  is  removed,  so  that
                         command will never again be  invoked.  Returns  an
                         empty string.
          trace list type name
               Where type is either command or variable.
                    trace list command name
                         Returns a list containing  one  element  for  each
                         trace currently set on command name. Each  element
                         of the  list  is  itself  a  list  containing  two
                         elements, which are the   opList    and    command
                         associated with the trace. If  name  doesn't  have
                         any traces set, then the  result  of  the  command
                         will be an empty string. If  name  doesn't  exist,
                         the command will throw an error.
                    trace list variable name
                         Returns a list containing  one  element  for  each
                         trace currently set on variable name. Each element
                         of the  list  is  itself  a  list  containing  two
                         elements, which are the   opList    and    command
                         associated with the trace. If name  doesn't  exist
                         or doesn't have any traces set, then the result of
                         the command will be an empty string.
     For backwards compatibility, three other subcommands are available:
          trace variable name ops command
               This is equivalent to trace add variable name ops command.
          trace vdelete name ops command
               This is equivalent to trace remove variable name ops command
                
          trace vinfo name
               This is equivalent to trace list variable name
     These subcommands are deprecated and  will  likely  be  removed  in  a
     future version of Tcl. They use an older syntax in which array,  read,
     write, unset are replaced by a, r, w and u respectively, and  the  ops
     argument is not a list, but  simply  a  string  concatenation  of  the
     operations, such as rwua.


SEE ALSO
     set, unset

KEYWORDS 
     read, command, rename, variable, write, trace, unset







_________________________________________________________________

NAME
     unknown - Handle attempts to use non-existent commands

SYNOPSIS
	unknown cmdName ?arg arg ...?

_________________________________________________________________

DESCRIPTION 
     This command is invoked by the Tcl interpreter whenever a script tries
     to invoke a command that doesn't exist. The implementation of  unknown
     isn't part of the Tcl core; instead, it is a library procedure defined
     by default when Tcl starts up. You can override the default unknown to
     change its functionality.
     If the Tcl interpreter encounters a command name for  which  there  is
     not a defined command, then Tcl checks for the existence of a  command
     named unknown. If there is  no  such  command,  then  the  interpreter
     returns an error. If the unknown command exists, then  it  is  invoked
     with arguments consisting of the fully-substituted name and  arguments
     for the original non-existent command. The unknown  command  typically
     does things like searching through library directories for  a  command
     procedure with the name  cmdName,  or  expanding  abbreviated  command
     names to full-length, or automatically executing unknown  commands  as
     sub-processes. In some cases (such as expanding abbreviations) unknown
     will change the original command slightly and  then  (re-)execute  it.
     The result of the unknown command  is  used  as  the  result  for  the
     original non-existent command.
     The default implementation of unknown behaves  as  follows.  It  first
     calls the auto_load library procedure to load  the  command.  If  this
     succeeds, then it executes the  original  command  with  its  original
     arguments. If the auto-load fails then unknown  calls  auto_execok  to
     see if there is an executable file by the name cmd. If so, it  invokes
     the Tcl exec command with cmd and all the args as  arguments.  If  cmd
     can't be auto-executed, unknown checks  to  see  if  the  command  was
     invoked at top-level and outside of any script. If  so,  then  unknown
     takes two additional steps. First, it sees  if  cmd  has  one  of  the
     following three forms: !!, !event, or ^old^new?^?. If so, then unknown
     carries out history substitution in the same way that  csh  would  for
     these constructs. Finally, unknown checks to see if cmd  is  a  unique
     abbreviation for an existing  Tcl  command.  If  so,  it  expands  the
     command name and executes the command with the original arguments.  If
     none of the above efforts  has  been  able  to  execute  the  command,
     unknown generates an error return. If the global variable  auto_noload
     is defined, then the auto-load step is skipped. If the global variable
     auto_noexec is defined then  the  auto-exec  step  is  skipped.  Under
     normal circumstances the return value from unknown is the return value
     from the command that was eventually executed.


SEE ALSO
     info, proc

KEYWORDS 
     error, non-existent command






_________________________________________________________________

NAME
     unset - Delete variables

SYNOPSIS
	unset ?--? ?-nocomplain? ?name name name ...?

_________________________________________________________________

DESCRIPTION 
     This command removes one or more variables. Each name  is  a  variable
     name, specified in any of the ways acceptable to the set command. If a
     name refers to an element of an array then  that  element  is  removed
     without affecting the rest of the array. If  a  name  consists  of  an
     array name with no parenthesized  index,  then  the  entire  array  is
     deleted. The unset command returns  an  empty  string  as  result.  If
     -nocomplain is specified as the first argument,  any  possible  errors
     are suppressed. The  option  may  not  be  abbreviated,  in  order  to
     disambiguate it from possible variable  names.  --  may  be  specified
     prior to -nocomplain to  prevent  it  from  being  interpreted  as  an
     option. If an error occurs, any variables after the named one  causing
     the error not deleted. An error can  occur  when  the  named  variable
     doesn't exist, or the name refers to an array element but the variable
     is a scalar, or the name  refers  to  a  variable  in  a  non-existent
     namespace. 


SEE ALSO
     set, trace

KEYWORDS 
     remove, variable






_________________________________________________________________

NAME
     update - Process pending events and idle callbacks

SYNOPSIS
	update ?idletasks?

_________________________________________________________________

DESCRIPTION 
     This command is used to  bring  the  application  ``up  to  date''  by
     entering the event loop repeatedly until all pending events (including
     idle callbacks) have been processed.
     If the idletasks keyword is specified as an argument to  the  command,
     then no new events or errors are processed; only  idle  callbacks  are
     invoked. This causes operations that are normally  deferred,  such  as
     display updates  and  window  layout  calculations,  to  be  performed
     immediately. 
     The update idletasks command is useful in scripts where  changes  have
     been made to the application's state and you  want  those  changes  to
     appear on the display immediately, rather than waiting for the  script
     to complete. Most display updates are performed as idle callbacks,  so
     update idletasks will cause them to run. However, there are some kinds
     of updates that only happen in  response  to  events,  such  as  those
     triggered by window size changes; these  updates  will  not  occur  in
     update idletasks.
     The update command with no options is useful in scripts where you  are
     performing a long-running computation but  you    still    want    the
     application to respond to events such as  user  interactions;  if  you
     occasionally call update then user input will be processed during  the
     next call to update.


SEE ALSO
     after, bgerror

KEYWORDS 
     event, flush, handler, idle, update






_________________________________________________________________

NAME
     uplevel - Execute a script in a different stack frame

SYNOPSIS
	uplevel ?level? arg ?arg ...?

_________________________________________________________________

DESCRIPTION 
     All of the arg arguments are concatenated as if they had  been  passed
     to concat; the result  is  then  evaluated  in  the  variable  context
     indicated by level. Uplevel returns the result of that evaluation.
     If level is an integer then it gives  a  distance  (up  the  procedure
     calling stack) to move before executing the command. If level consists
     of # followed by a number then the  number  gives  an  absolute  level
     number. If level is omitted then it defaults to  1.  Level  cannot  be
     defaulted if the first command argument starts with a digit or #.
     For example, suppose that procedure a was invoked from top-level,  and
     that it called b, and that b called c.  Suppose  that  c  invokes  the
     uplevel command. If level is 1 or #2 or omitted, then the command will
     be executed in the variable context of b. If level is 2 or #1 then the
     command will be executed in the variable context of a. If level  is  3
     or #0 then the command will be  executed  at  top-level  (only  global
     variables will be visible).
     The uplevel command causes the invoking procedure  to  disappear  from
     the procedure calling stack while the command is  being  executed.  In
     the above example, suppose c invokes the command uplevel 1 {set x  43;
     d} where d is another Tcl procedure. The set command will  modify  the
     variable x in b's context, and d will execute at level 3, as if called
     from b. If it in turn executes the command uplevel {set x 42} then the
     set command will modify the  same  variable  x  in  b's  context:  the
     procedure c does not appear  to  be  on  the  call  stack  when  d  is
     executing. The command ``info level'' may be used to obtain the  level
     of the current procedure.
     Uplevel makes it possible to implement new control constructs  as  Tcl
     procedures (for example, uplevel could be used to implement the  while
     construct as a Tcl procedure).
     namespace eval is another way (besides procedure calls) that  the  Tcl
     naming context can change. It adds  a  call  frame  to  the  stack  to
     represent the  namespace  context.  This  means  each  namespace  eval
     command counts as another call level for uplevel and  upvar  commands.
     For example, info level 1 will return a list describing a command that
     is either the outermost procedure call or the outermost namespace eval
     command. Also, uplevel #0 evaluates  a  script  at  top-level  in  the
     outermost namespace (the global namespace).


SEE ALSO
     namespace, upvar

KEYWORDS 
     context, level, namespace, stack frame, variables






_________________________________________________________________

NAME
     upvar - Create link to variable in a different stack frame

SYNOPSIS
	upvar ?level? otherVar myVar ?otherVar myVar ...?

_________________________________________________________________

DESCRIPTION 
     This command arranges for one or more local variables in  the  current
     procedure to refer to variables in an enclosing procedure call  or  to
     global variables. Level may have any of the forms  permitted  for  the
     uplevel command, and may be omitted if the first letter of  the  first
     otherVar isn't # or a digit (it defaults  to  1).  For  each  otherVar
     argument, upvar makes the variable by that name in the procedure frame
     given by level (or at global level, if level is #0) accessible in  the
     current procedure  by  the  name  given  in  the  corresponding  myVar
     argument. The variable named by otherVar need not exist at the time of
     the call; it will be created the first time myVar is referenced,  just
     like an ordinary variable. There must not exist a variable by the name
     myVar at the time upvar is invoked. MyVar is  always  treated  as  the
     name of a variable, not an array element. Even if the name looks  like
     an array element,  such  as  a(b),  a  regular  variable  is  created.
     OtherVar may refer to  a  scalar  variable,  an  array,  or  an  array
     element. Upvar returns an empty string.
     The  upvar  command  simplifies  the  implementation  of  call-by-name
     procedure calling and also  makes  it  easier  to  build  new  control
     constructs as Tcl procedures.  For  example,  consider  the  following
     procedure: proc add2 name { upvar $name x set x [expr $x+2] } Add2  is
     invoked with an argument giving the name of a variable,  and  it  adds
     two to the value of that  variable.  Although  add2  could  have  been
     implemented using uplevel instead of upvar, upvar makes it simpler for
     add2 to access the variable in the caller's procedure frame.
     namespace eval is another way (besides procedure calls) that  the  Tcl
     naming context can change. It adds  a  call  frame  to  the  stack  to
     represent the  namespace  context.  This  means  each  namespace  eval
     command counts as another call level for uplevel and  upvar  commands.
     For example, info level 1 will return a list describing a command that
     is either the outermost procedure call or the outermost namespace eval
     command. Also, uplevel #0 evaluates  a  script  at  top-level  in  the
     outermost namespace (the global namespace).
     If an upvar variable is unset  (e.g.  x  in  add2  above),  the  unset
     operation affects  the  variable  it  is  linked  to,  not  the  upvar
     variable. There is no way to unset an upvar variable except by exiting
     the procedure in which it is  defined.  However,  it  is  possible  to
     retarget an upvar variable by executing another upvar command.


Traces and upvar
     Upvar interacts with traces in a    straightforward    but    possibly
     unexpected manner. If a variable trace is defined  on  otherVar,  that
     trace will be triggered by actions involving myVar. However, the trace
     procedure will be passed the name of myVar, rather than  the  name  of
     otherVar. Thus, the output of the  following  code  will  be  localVar
     rather than originalVar: proc traceproc { name index op } { puts $name
     } proc setByUpvar { name value } { upvar $name localVar  set  localVar
     $value } set originalVar 1  trace  variable  originalVar  w  traceproc
     setByUpvar originalVar 2 } If otherVar refers  to  an  element  of  an
     array, then variable traces set for  the  entire  array  will  not  be
     invoked when myVar is accessed (but traces on the  particular  element
     will still be invoked). In particular,  if  the  array  is  env,  then
     changes made to myVar will not be passed to subprocesses correctly.


SEE ALSO
     namespace, uplevel

KEYWORDS 
     context, frame, global, level, namespace, procedure, variable






_________________________________________________________________

NAME
     variable - create and initialize a namespace variable

SYNOPSIS
	variable ?name value...? name ?value?

_________________________________________________________________

DESCRIPTION 
     This command is normally used  within  a  namespace  eval  command  to
     create one or more variables within a namespace. Each variable name is
     initialized with value. The value for the last variable is optional.
     If a variable name does not exist, it is created.  In  this  case,  if
     value is specified, it is assigned to the newly created  variable.  If
     no value is specified, the new variable  is  left  undefined.  If  the
     variable already exists, it is set to value if value is  specified  or
     left unchanged if no value is given.  Normally,  name  is  unqualified
     (does not include the names of any  containing  namespaces),  and  the
     variable is created in the current namespace.  If  name  includes  any
     namespace  qualifiers,  the  variable  is  created  in  the  specified
     namespace. If the variable is not defined, it will be visible  to  the
     namespace which command, but not to the info exists command.
     If the variable  command  is  executed  inside  a  Tcl  procedure,  it
     creates local variables linked to    the    corresponding    namespace
     variables. In this way  the  variable  command  resembles  the  global
     command, although the global command only links to  variables  in  the
     global namespace. If any values are given, they are used to modify the
     values of the associated namespace variables. If a namespace  variable
     does not exist, it is created and optionally initialized.
     A name argument cannot reference an element within an array.  Instead,
     name should reference the entire array, and the  initialization  value
     should be left off. After the variable  has  been  declared,  elements
     within the array can be set using ordinary set or array commands.


SEE ALSO
     global, namespace

KEYWORDS 
     global, namespace, procedure, variable






_________________________________________________________________

NAME
     vwait - Process events until a variable is written

SYNOPSIS
	vwait varName

_________________________________________________________________

DESCRIPTION 
     This command enters the Tcl event loop to process events, blocking the
     application if no events are ready.  It  continues  processing  events
     until some event handler sets the  value  of  variable  varName.  Once
     varName has been set, the vwait command will return  as  soon  as  the
     event handler that modified varName completes. varName  must  globally
     scoped (either with a call to global for the varName, or with the full
     namespace path specification).
     In some cases the vwait  command  may  not  return  immediately  after
     varName is set. This can happen if the event handler that sets varName
     does not complete immediately. For example, if an event  handler  sets
     varName and then itself calls vwait to wait for a different  variable,
     then it may not return for a long time. During this time the top-level
     vwait is blocked waiting for the event  handler  to  complete,  so  it
     cannot return either.


SEE ALSO
     global 

KEYWORDS 
     event, variable, wait





_________________________________________________________________

NAME
     while - Execute script repeatedly as long as a condition is met

SYNOPSIS
	while test body

_________________________________________________________________

DESCRIPTION 
     The while command evaluates test as an expression  (in  the  same  way
     that expr evaluates its argument). The value of the expression must  a
     proper boolean value; if it is a true value then body is  executed  by
     passing it to the Tcl interpreter. Once body has  been  executed  then
     test is evaluated again, and the process repeats until eventually test
     evaluates to a false boolean value. Continue commands may be  executed
     inside body to terminate the current iteration of the loop, and  break
     commands may be executed inside body to cause immediate termination of
     the while command. The while command always returns an empty string.
     Note: test should  almost  always  be  enclosed  in  braces.  If  not,
     variable substitutions will be made before the  while  command  starts
     executing, which means that variable changes made  by  the  loop  body
     will not be considered in the expression. This is likely to result  in
     an infinite loop. If test  is    enclosed    in    braces,    variable
     substitutions are delayed until the expression  is  evaluated  (before
     each loop iteration), so changes in the variables will be visible. For
     an example, try the following  script  with  and  without  the  braces
     around $x<10: set x 0 while {$x<10} { puts "x is $x" incr x }

SEE ALSO
     break, continue, for, foreach

KEYWORDS 
     boolean value, loop, test, while
